Perf: switching to a MEMBER tab runs the parent PROGRAM's full validation concurrently with the member's - two heavy passes fight

[msarson]

Symptom ([357A BUILD] retest, 2026-07-14 — tab switch, no restart)

Switching from IBSCommon.clw to SelectJobNumber_IBSCommon.clw (a MEMBER of the IBSCommon PROGRAM, still open in another tab) runs TWO full async validation passes at the same time, interleaved on the single event loop:

• SelectJobNumber (caller=onDidOpen, 2,643 tokens): total 10,967ms — discardedReturn 8,949ms, missingIncludes 9,278ms, undeclaredVar 2,507ms
• IBSCommon (caller=crossFileUpdate, 68,486 tokens): total 9,846ms — undeclaredVar 9,042ms, missingConstants 9,060ms, missingImpl 1,960ms

Their perf lines interleave (11:21:17-11:21:26) and both finish ~simultaneously at +10-11s, each inflated by the other. Solo, SelectJobNumbers pass is far quicker (earlier warm runs: 2-3s); here it is dragged to ~11s by the parents concurrent 68k-token pass — for a tab the user just left.

Mechanism

onDidOpen validates only the opened doc. revalidateRelatedDocuments (stamps crossFileUpdate) fires from onDidChangeContent and re-validates OTHER open docs related to the changed one — a member change re-validates the open parent PROGRAM "so cross-file diagnostics clear" (server.ts:1516-1519). On tab activation the client emits a didChange, so the parent PROGRAM (IBSCommon, 68k tokens) gets a full pass concurrent with the member`s.

Two problems:

1. No document-level serialization / priority. Startup responsiveness — audit fix plan (tracking issue with TODOs) #297 serialized validators WITHIN one document`s pass; two separate validateTextDocument calls (different docs) still interleave and contend — the Phase-A (Design: startup I/O schedule - sequential background lane + RED-shape freshness tiers (stop paying per-file verification on every start) #357) contention lesson, one level up. The VISIBLE document should be prioritized; background related-doc revalidation should not fight it.
2. Possibly-unnecessary parent revalidation. Re-validating the parent PROGRAM makes sense when a member is EDITED (its cross-file diagnostics may shift). On a mere tab switch / open (no semantic change), it may be pure waste — worth gating on an actual content delta.

Fix direction (investigate-first)

• Confirm the exact client trigger (spurious didChange on tab activation vs real edit); if no real delta, skip the related-doc revalidation.
• Serialize document async passes (or prioritize the active/visible document and debounce/queue related-doc revalidation behind it) so two heavy passes never interleave.

Bonus data point (feeds #358)

IBSCommon`s undeclaredVar dropped 23,993ms (first open, cold) → 9,042ms here, because the in-memory chain index survived the session (DRIVEROPTIONS 18,491ms → 189ms). BUT it is still 9s WARM — dominated by the 51 unresolved template-equate names (findSymbol 6,001ms). So the #358 template-equate filter saves ~9s on EVERY validation of this file, not just the one-time cold build — filter > persistence for this path.

Surfaced by the #357 Phase-A retest. Related: #357 (background lane), #358 (chain-index/template-equate), #295 (off-thread).

[msarson]

Concrete map from the 5-agent startup-freeze investigation (2026-07-15)

validateTextDocument (server.ts:638) is dispatched unawaited from many sites, and nothing coalesces concurrent passes for the same doc:

• onDidOpen (:616), onDidChangeContent (:1534) which then also fires the PROGRAM/MEMBER parent's validation via revalidateRelatedDocuments → validateTextDocument(openDoc,'crossFileUpdate') (:1333, :1347) — member + parent run concurrently, neither awaited (the exact Perf: switching to a MEMBER tab runs the parent PROGRAM's full validation concurrently with the member's - two heavy passes fight #359 shape).
• onDidChangeWatchedFiles (:1387-1389) and solutionReady (:2129-2131) both loop over EVERY open doc, unawaited.
• Only the 'sdiReady' lane (:2267-2272) sequences docs with await.

Worse: inside validateTextDocument, the 8 async validators run via Promise.all for every caller except 'sdiReady' (:802-813) — so routine edits get the unmitigated concurrent stampede the startup lane was specifically fixed to avoid (see #367 for that half).

The version-skip guard (:652) exempts crossFileUpdate by design (content unchanged, related file changed) but there is no in-flight coalescing — two overlapping passes for the same (uri, version) both run to completion. (We saw this concretely: two identical isClassIncluded builds 4ms apart, each ~5s — #366.)

Fix: replace lastValidatedVersions: Map<uri,number> (:635) with an in-flight-promise map Map<uri,{version, promise}> — a second caller for the same (uri, version) awaits the existing pass instead of starting a new 8-validator run. Same pattern already proven for the reachable-set BFS (IncludeVerifier.ts:267-272, #366). Effort M; must preserve the crossFileUpdate "revalidate on related change" semantics (coalesce only truly-concurrent same-version requests).

[msarson]

Fixed in a8f98008 (on version-1.0.1, pushed) — rig-reproduced and verified on the real solution

Root cause, sharpened: the vscode-languageserver TextDocuments manager fires onDidChangeContent for every didOpen (an echo of the same event), and tab activation can emit a no-op didChange. Each identical-content event ran the full change pipeline: cache evictions, a second validation of the just-validated document, and revalidateRelatedDocuments — which ran the 68k-token parent PROGRAM's full pass concurrently with the member's. So the stampede didn't need an edit at all; merely opening/activating a member triggered it.

Fix: ContentChangeGuard (vscode-free util, unit-tested) — content snapshot on didOpen; any change event whose content matches the snapshot returns before any pipeline work; genuine edits re-snapshot and run exactly as before, including the parent re-validation that clears cross-file diagnostics. Length-first compare, sha1 only on equal lengths; snapshot dropped on close. Safe against the startup deferral: the sdiReady lane re-validates all open docs itself, so the echo was never load-bearing.

Measured (headless scenario, ap1.sln, IBSCommon 68k tokens + SelectJobNumber member — the exact files from the original trace):

	Pre-fix	Post-fix
Member open → parent crossFileUpdate pass	1 full pass, 10,342ms concurrent	none
Member's own validation	11,188ms (dragged)	2,689ms (solo speed — matches the issue's 2-3s solo baseline)
No-op didChange (tab-activation shape)	parent 1,766ms + member 1,924ms re-validated	zero validation activity

Note on remaining intentional behavior: a genuine member edit still re-validates the open parent (that's the cross-file-diagnostics contract) — the two passes only coexist when there is a real change to reconcile.

Tests: 6 new ContentChangeGuard cases. Suite 2320 green.