vibe-qcDocumentation

Dependent factor traversal and ordered assembly¶

Date: 3 November 2026. Implementing issue: TENS-08 (#801). This source increment extends the stream contract and bounded schedule keys. It does not complete sparse/symmetry representations or scientific acceptance of a runtime.

Selected physical consumer and missing capability¶

The actual consumer is build_periodic_gaussian_local_orbital_factor_panel, which feeds the certified-real Gaussian selected-pair MP2 provider. It computes a rectangular complex [auxiliary,left,right] panel for one selected q/auxiliary slice. The existing LocalPanelPlan checks the coefficient-product and AO-pair reduction IR and retains the optimized compensated CPU kernel. The new representation capability replaces the count-only inner traversal.

Native contract	Current representation binding
AO-pair map	Ordered `mu*n+nu`, parent AO space, contiguous tiles of at most `ao_pair_block`, possibly a shorter final tile; the entire map is an affine `Domain`.
Local orbital maps	Independently selected left/right ranges in the authenticated local-basis frame; their dimensions can differ. Parent identity and ordered coordinates remain part of every view.
Iteration order	k in native order, then AO-pair tiles, then the registered kernel’s AO-pair/auxiliary/left/right loops. No reorder or q/-q shortcut.
Source authority	Captured HF/context, actual gauge, occupied indices, PAO selection, local-basis certificate, q source/opposite-source and principal whitener are checked by the existing method before adaptation. Every returned native tile’s descriptor and identities are checked again.
Ownership	Native factor tile lives through its synchronous callback; coefficient/output owners and compensation live for the panel call. The existing imported native inventory charges each owner once.
Replay	The Gaussian producer can reconstruct tiles, but this admitted traversal requests one pass per k. No repeated consumer, numeric replay store or hidden reader is introduced.
Numerical policy	Complex FP64, independent coefficient conjugation/orientation, unchanged multiplication association and real/imaginary compensation; final `(sum+correction)*(1/Nk)/sqrt(Nk)` stays in the method.
Caps	Original numerical/node/rank inventory, work, image candidates, tile-call census and reader qualifications remain authoritative. The existing 65,536-byte worker control envelope contains the new fixed metadata.

StreamCursor alone checks source, sequence and visit count. It cannot certify that a provider covers the requested ordered domain, or express single-pass replay and absence/duplicate policies. DependentStream adds those checks using the existing Domain, SourceStamp, BorrowScope, Budget and numerical modes. No second descriptor, allocator or scientific source registry is created. The physical change does not migrate a complete ragged PNO batch or make a new Gaussian producer qualification claim.

Bounded representation capability¶

The method supplies one parent-bound affine domain at a time. It enumerates parent domains lazily; each can have a different extent, including zero. The cursor retains only that domain, source/pattern revisions, policy and counters. It emits the exact next ordered subdomain, validates each returned map before arithmetic, and requires a terminal contribution for every tile. It never pads parents to a maximum dimension or builds a global descriptor or offset table. Non-affine selected slicing explicitly refuses; the core’s existing selected maps and #804 portable bindings are not replaced.

Each stream belongs to one caller and does not permit concurrent use. The provider callback and each accepted contribution are synchronous. BorrowScope must remain active before requests and after numerical work. The numerical executor still acquires its ordinary input/output leases and checks native value versions. Provider, allocation, arithmetic, expired-scope or incomplete-emission failure poisons the cursor. Swallowing an emission exception does not allow a successful traversal. Partial accumulation is private to the method; failure discards the panel rather than rolling back individual additions. Retaining callback handles or mutating imported raw storage outside the existing lease contract is unsupported.

A declared pass count is checked before requesting any tile. A single-pass cursor refuses multiple passes and any second execution. Replayable cursors allow bounded repeated traversal of a provider that actually guarantees replay. Creating a fresh cursor does not manufacture replay capability: a provider must retain and enforce its traversal state for the resource being consumed. There is no implicit materialization of a single-pass source.

Presence / assembly	Implemented meaning
Evaluated	Invoke the checked numerical operation; numerical zero remains evaluated data.
Structural zero	Skip arithmetic only with an explicit method-issued certificate matching the current pattern revision and the validated tile domain. The token records authority, not a proof inferred from values.
Screened omission	Distinct refusal requiring a method error policy; never converted to structural zero.
Underflow omission	Distinct refusal; never interpreted as an exact missing sector.
Unavailable / provider exception	Fail the traversal and discard unpublished output.
Unique contribution	Exactly one terminal emission per requested tile. Duplicate or missing emissions fail.
Ordered additive contributions	Explicit per-tile bound, contiguous ordinals starting at zero, terminal marker and visit cap. The consumer performs its declared ordered reduction; complex fixtures use the existing compensated update. No sorting/reassociation is implied.

The production Gaussian adapter emits evaluated unique contributions only. Exact missing sectors and additive duplicates are independently tested capabilities, not newly migrated production sparse representations. Signs, conjugation, multiplicities and sector reconstruction belong to the method. Hermitian/antisymmetric packed storage, arbitrary sparse scatter and insert/sort/merge workspaces remain unimplemented in this increment.

Admission and cache boundary¶

The cursor reserves its object, emission controls, current-domain copies, counters and a fixed StructuralKey temporary allowance on the same ledger. There is no allocation per successful enumeration step; an allocation-disabled fixture verifies this. Callback payload, retained owners, output and assembly scratch must already be admitted or allocated through that ledger. The physical adapter imports the same native inventory once and uses the existing control envelope, so this change adds no new public resource-cap component. Original work bounds include 8,192 control/planning units per tile and continue to cover fixed metadata checks. Global factor/visit censuses are unchanged.

Before reads, the cursor checks the declared worst-case product of tile count, contributions per tile and pass count against its visit cap, with overflow checks. It supports ordered direct assembly only, so there is no additional sort/hash workspace. Existing output plus compensation remain charged until publication. The generated large-domain test keeps factor and output owners on Budget and proves exact/one-byte-below total admission.

The existing StructuralKey gains enumeration and assembly limits. Its traversal key includes current domain and parent revisions/coordinates, source/metric/frame/partition, pattern, numerical/replay/assembly policy, block size, visit bounds, current cap and available bytes. A contraction cache must additionally append its operand schemas, layout, conjugation and operation identity. The traversal key alone is not an executable contraction cache key. Fresh bindings and current IR/leases are still required. There is no numeric cache and no production cache added for this fixed traversal.

#804’s portable IDs, descriptor-to-native bindings, bounded registry and completion states remain unchanged. This local synchronous cursor needs no wire identifier or async owner. Its Domain is compatible with the existing local binding target; portable selected/dependent metadata does not imply that #804’s current real MPI arithmetic accepts it. Remote ragged execution and lease completion remain separate concrete #804 work.

Focused numerical and resource evidence¶

Twenty-seven core/stream/planner/representation/distributed source cases pass. The six new representation cases also pass ASan/UBSan, and warning-enabled C++17 compilation is clean. The changed physical panel translation unit compiles with the checkout’s native build flags. Tests include:

Unequal complex 2-by-5 panels, explicit bilinear and Hermitian variants, bitwise predecessor sum/correction parity and independent long-double sums.
Lazy parent domains with auxiliary extents 0, 1, 7 and 67, 2-by-3 local outputs and tile capacity five; no parent table or padding.
Exact missing sectors, rejection of screened/underflow/unavailable omissions, explicit additive cancellation, duplicate/order/terminal checks and replay refusal before a single-pass source is consumed.
Revised or mismatched maps/parents/source/pattern, lower-budget cache misses, both new cache-limit fields, conflicting and expired leases, allocator and provider failures, failed consumers and swallowed-exception refusal.
Exact peak and one byte below it, control-admission refusal before requests, and 20,004 parent domains representing 30,006,000 logical factor bytes at a constant 6,688-byte tracked peak. Four parents have the same peak.

That last result qualifies generated transport/assembly boundedness only. It is not evidence for a physical Gaussian producer or infinite-image limit.

Measured cost¶

benchmarks/tensor_representation.cpp compares the existing registered LocalPanelPlan plus StreamCursor against the same kernel with dependent coverage, using identical generated complex factors and bitwise output checks. Apple M5 Max, Apple Clang 21, C++17 -O3 -DNDEBUG, one caller CPU thread, no BLAS or Eigen linkage. Thirty-one alternating samples give medians; the instrumented baseline and new path both include factor generation, fresh IR, leases and accumulation. This is a whole traversal microbenchmark, not whole-method chemistry timing.

AO, aux, left, right; block	Visits / final extent	Existing / dependent us	Ratio	Existing / dependent tracked peak bytes
7, 3, 2, 5; 11	5 / 5	10.750 / 10.792	1.004	8928 / 11008
17, 11, 1, 3; 31	10 / 10	51.125 / 51.167	1.001	14256 / 16336
17, 11, 7, 13; 31	10 / 10	1102.083 / 1103.958	1.002	49584 / 51664
31, 7, 3, 11; 19	51 / 11	928.875 / 932.708	1.004	23120 / 25200

The 2,080-byte increment includes the fixed traversal-key allowance. No packing, conversion, padding or sort workspace is used. A separate allocation-free traversal measures enumeration; assembly is the registered compensated arithmetic itself. Timers perturb small stages, and stage medians need not sum to a median whole call.

Shape row above	Fresh cursor plan us	First dependent call us	Enumeration us	Fresh IR us	Factor generation us	Assembly us	Repeats 1 / 10 / 1000, us per call
1	0.083	20.833	0.208	2.583	0.251	6.667	10.708 / 10.725 / 10.125
2	0.125	51.167	0.208	4.791	4.128	40.333	51.167 / 51.217 / 53.041
3	0.167	1100.958	0.500	5.667	4.210	1089.417	1128.875 / 1207.433 / 1242.997
4	0.125	927.708	1.167	26.500	9.924	882.501	1444.542 / 1075.792 / 1039.029

Fresh cursor construction is sampled separately after the first traversal; first dependent execution follows one baseline warmup. Repeats construct a new stream each time, as the physical adapter does. They do not reuse numeric factors in a new cache. A second process run gives ratios 1.008/1.002/1.000/1.002 and 1000-call means 11.522/57.809/1286.339/993.948 us. Earlier paired pilot ratios ranged 0.904-1.011; their absolute times were slower in both paths. Noise and longer-run slowdown are retained; no speedup is asserted. Direct ordered traversal is retained because this consumer already has ordered dense tiles and the extra checks are small. A sparse conversion/search policy has no measured justification here.

The first benchmark process measured maximum RSS 2,293,760 bytes and peak memory footprint 1,802,648 bytes. Those process measurements include executable, allocator/runtime and reference arrays outside the tensor ledger; they are not the per-operation peak or an exact external-workspace estimate. Tracked bytes and process memory remain distinct.

Runtime acceptance and remaining work¶

The current local physical test refuses the incomplete basis overlay before any integral calculation. The inspected vq inventory has scheduler-only development QC registration and an older release runtime, with no containing build verified for this change. Existing runtime/validation ownership and jobs were preserved. No stale runtime, integrity bypass, duplicate managed build, full-method result or matched-reference PASS is claimed.

Validator must use a containing runtime for the admitted finite-source HF plus selected-pair MP2 workflow at unchanged settings, retaining source/native identity, factor equality, energies and resource census. Use matched CRYSTAL where applicable; otherwise justify same-source independent sums/known limits and retain the finite-source limitations. Source checks do not establish production periodic correlation or infinite-image convergence. Exact source and inspected runtime hashes, raw timings and operational evidence are on #801 outside the product checkout. #793/#799/#800/#801 remain open as applicable.

Next representation work includes non-affine selected slicing, arbitrary sparse assembly/conversion, symmetry-packed reconstruction, true multi-parent ragged layouts, provider-backed replay stores and remote completion. Existing exact RI factors are preserved; new compression and mixed precision require separate scientific authority. Fock/state #472, reference/factor #580/#581 and provider #617 ownership remain unchanged.

Primary-source basis and departures¶

Finch, DOI 10.1145/3720473, sections 3-7: frozen iteration metadata and explicit read/update/assembly lifecycle. This is a synchronous C++ cursor, not Finch looplets or a Julia compiler.
Sparse workspaces, DOI 10.1145/3656426, sections 4-7: insertion/deduplication order and workspace policy must be explicit. Ordered direct assembly avoids ISM’s accumulation/all arrays here; general insert-sort-merge is not implemented.
CoRa, arXiv:2110.10221, sections 4-7: dependent extents and metadata/prelude costs matter. This cursor does not generate fused-loop offset tables or pad domains. Its strict complex results cannot be inferred from CoRa’s single-precision compiler timings.
CoNST, arXiv:2401.04836, sections 3-5.1: retain factor contractions and measure against the best existing layout. No constraint compiler or fast-math DLPNO performance claim is adopted.
UniSparse, DOI 10.1145/3649816, sections 4-5: logical-to-physical maps and conversions are explicit operations. This affine subset refuses unsupported map conversion instead of silently materializing it.