fix(quickfiler): carry the initialised folder predictor to the item controller (#678)

[drmoisan]

fix(quickfiler): carry the initialised folder predictor to the item controller

Summary

• An accepted high-confidence QuickFiler item is no longer scored a second time after Show(). The folder predictor the dequeue-time confidence gate already initialised is carried forward to QfcItemController instead of being discarded and rebuilt.
• The carry is implemented on both display legs: leg A (the first page, through QfcHomeController.RunAsync) and leg B (every subsequent page, through IterateQueueAsync into QfcQueue).
• Leg A displays the post-unhook item set. Carriers are reconciled against QfcDequeueBatch.Items rather than consumed directly from QfcDequeueBatch.PreScored, so an item whose EmailMoveMonitor unhook failed is not displayed and a substitute pulled from the master queue is not silently dropped.
• The carried predetermined folder and the FolderArray entries now use the same archive-prefix projection, so FolderContains matches for archive-rooted suggestions instead of falling through to an index default.
• 22 of 23 acceptance criteria pass. AC20 is recorded as PARTIAL and left unchecked; it is not claimed as delivered. Details under Follow-ups.

Why

Issue #678 records the consumer-side work needed to remove a redundant per-item scoring pass in High Confidence mode. Preparation research established that carrying only the top-folder string does not remove the second pass: FolderArray, Suggestions and FolderRowArray are all produced from _folderHandler, so the item controller still had to run FolderPredictor.InitAsync(FromField) on every accepted item even when a fully initialised predictor already existed upstream. FolderScoringService.ScoreAsync built that predictor and returned only (score, topFolder), so the initialised instance never reached the caller.

The user-visible effect was wasted work rather than incorrect behaviour: slower folder-combo population and redundant Outlook COM traffic proportional to the number of rows on screen.

What Changed

Producer and carrier chain

• QfcPreScoredItem carries an IFolderSearchHandler alongside its existing MailItem and PredeterminedFolder members, which keep their names, types and non-null contracts.
• IFolderScoringService.ScoreAsync and FolderScoringService publish the handler they initialise instead of discarding it.
• The handler is forwarded through the QfcStreamingDequeueConfidenceGate scoreLoader delegate, its acceptance projection, and QfcDatamodel.QueueProcessing.ScoreRemainingQueueMailItemAsync, so it is present on QfcGateBatch.Accepted and QfcDequeueBatch.PreScored.

Consumers

• Leg A: RunAsync selects the outcome-returning dequeue and the IList<QfcPreScoredItem> overload of LoadItemsAsync. High-confidence-disabled mode continues to select the IList<MailItem> overload unchanged.
• Leg B: IterateQueueAsync forwards batch.PreScored into QfcQueue.EnqueueAsync, which carries the handler to the QfcItemController instances it constructs.
• QfcItemController.LoadFolderHandlerAsync adopts a carried handler inside its varList is null branch only. The FromArrayOrString branches of both LoadFolderHandler and LoadFolderHandlerAsync are unchanged, and a carried handler is never adopted on a FromArrayOrString call.
• The carried handler is released in QfcItemController cleanup alongside _folderHandler.

Correctness work from the post-review remediation cycle

• QfcPreScoredItem.ResolveCarrier and ReconcileCarriersToItems make batch.Items the leg A spine. Matching is by reference identity first, then EntryID. An item with no matching carrier receives a carrier with a null handler and is scored normally at display time.
• ProjectPredeterminedFolder was aligned to FolderPredictor.ProjectSuggestionPath rather than narrowing the documented claim; UtilitiesCS is unmodified.
• The adoption path observes the cancellation token, matching the pre-change routes that reached the predictor through Task.Run(..., cancel).

Tests — new MSTest coverage for the single-initialisation invariant, the negative guard proving a carried handler is ignored when varList is non-null, archive-rooted projection, the leg A post-unhook reconciliation, and cancellation observation. Existing pinned tests were rewritten to assert the carrier overload rather than deleted or weakened.

Architecture / How It Fits Together

dequeue gate ──scores──> FolderScoringService (builds + initialises FolderPredictor)
     │                            │
     │                            └── publishes IFolderSearchHandler
     ▼
QfcGateBatch.Accepted ──> QfcDequeueBatch { Items (post-unhook), PreScored (carriers) }
     │
     ├── leg A: RunAsync ──> ReconcileCarriersToItems(Items, PreScored) ──> LoadItemsAsync(IList<QfcPreScoredItem>)
     │                                                                          └─> QfcCollectionController ─> QfcItemGroup ─> QfcItemController
     └── leg B: IterateQueueAsync ──> QfcQueue.EnqueueAsync ──> QfcItemController
                                                                    │
                                            LoadFolderHandlerAsync ─┴─ adopts carried handler (varList is null branch only)

ReconcileCarriersToItems is the leg A join. Items and PreScored are captured on opposite sides of UnhookDequeuedNodes, which is not read-only: on an UnhookItem throw, TryUnhookOrReplace removes the failed item, takes a replacement from the master queue and re-inserts it. Taking Items as the spine is what keeps the displayed set equal to the set that survived that pass.

Verification

Completed. Full C# toolchain in policy order, final uninterrupted pass:

Gate	EXIT	Summary
dotnet tool run csharpier format .	0	Formatted 1575 files in 2042ms. (tree observation before/after identical)
dotnet tool run csharpier check .	0	Checked 1575 files in 4937ms.
analyzer build (/t:Rebuild)	0	5 Warning(s), 0 Error(s)
nullable build (/t:Rebuild)	0	5 Warning(s), 0 Error(s), zero CS86 diagnostics
MSTest + coverage	0	Test Run Successful. Total 6949, Passed 6949, Failed 0, Skipped 0

Coverage, read directly from the post-processed Cobertura document rather than from a summary tool:

• Repository-wide line 85.3967%, branch 79.4522% (lines-covered 55086 / lines-valid 64506). Both rose against the same-session baseline.
• Changed-line coverage for the remediation cycle: 34/34 = 100.00%, with 89 added lines excluded as non-executable.
• Every new or modified member in a non-exempt class is at or above 90%.

These clear the 80% floor in CLAUDE.md and the 85% line / 75% branch floors in .claude/rules/general-unit-test.md and .claude/rules/quality-tiers.md.

Recommended for the reviewer.

dotnet tool run csharpier check .
msbuild TaskMaster.sln /t:Rebuild /m /p:Configuration=Debug "/p:Platform=Any CPU" /p:EnableNETAnalyzers=true /p:EnforceCodeStyleInBuild=true
msbuild TaskMaster.sln /t:Rebuild /m /p:Configuration=Debug "/p:Platform=Any CPU" /p:TreatWarningsAsErrors=true
pwsh -NoProfile -File scripts/vscode/Invoke-MSTestWithCoverage.ps1 -SearchRoot .

Backward Compatibility / Migration Notes

• No public API is removed or renamed. QfcPreScoredItem's two existing members keep their names, types and non-null contracts.
• QfcHighConfidencePreFilter.FilterAsync remains dormant and HighConfidencePreFilterLoader remains uninvoked. The Times.Never assertions that pin the landed decision of issue Feature: quickfiler-high-confidence-dequeue-streaming #233 are preserved verbatim.
• No [ExcludeFromCodeCoverage] attribute is added or removed anywhere in the change; verified at zero added and zero removed lines across the anchored diff.
• Accepted behavioural delta: reusing the scan-time suggestion set freezes conversation-derived (CtfMap) suggestions at scan time rather than re-deriving them at display time, on both legs. The scan-to-display interval is longer on leg B. Bayesian suggestions and the recents list are unaffected, because the folder array is still built lazily at display time.

Risks and Mitigations

• Stale suggestions on leg B. Mitigated by the fact that only the conversation-derived component is frozen; the interval is bounded by the queue iteration cadence. Called out above as an accepted, documented delta.
• Carrier/item mismatch on the unhook error path. This was a real defect found in review and fixed here; it is now pinned by a test that first asserts the divergence it produced, so the gate cannot pass on a hand-built pair.
• Reference-identity-first matching. Deliberate: an EntryID-less mock carrier in an existing passing test would be stranded by an EntryID-first matcher. The change only widens matching, never narrows it.
• Rollback is a straight revert of the two implementation commits; nothing outside QuickFiler and QuickFiler.Test is touched.

Review Guide

Suggested order:

1. QuickFiler/Controllers/QfcHighConfidencePreFilter.cs — the carrier, the scoring seam, and ResolveCarrier / ReconcileCarriersToItems.
2. QuickFiler/Controllers/QfcHomeController.cs and QfcHomeController.Iteration.cs — overload selection and the two legs.
3. QuickFiler/Controllers/QfcItemController.FolderHandling.cs — adoption, projection, cancellation.
4. QuickFiler/Controllers/QfcQueue.Enqueue.cs and QfcCollectionController.CarrierLoad.cs — new partial parts.
5. Tests, then evidence documents.

Mechanical noise to expect: QfcQueue.Enqueue.cs and QfcCollectionController.CarrierLoad.cs are new partial parts created to keep files at or under the 500-line limit. Much of their content is relocated, not new. QfcQueue.Enqueue.cs shows a per-file coverage drop from 28.00% to 15.29% that is not a regression: the uncovered line count is unchanged at exactly 72, and the ratio moved only because 15 covered lines were removed.

Footprint: 16 files under QuickFiler/, 20 under QuickFiler.Test/, 86 feature-folder documents, and nothing outside those three prefixes.

Follow-ups

None of the below is promoted here; they are being collected into a single consolidated issue filed separately.

• AC20 (PARTIAL, unchecked). Three of its four clauses hold. The "every new or modified member reaches 90%" clause fails for QfcQueue.EnqueueAsync (0/46) and LoadControllersViewersAsync (0/24). Both were equally uncovered before this change, so this is not a coverage regression — the combined QfcQueue surface improved from 41.47% to 44.90%. The criterion is self-limiting on those two members: covering them requires either a live Outlook window, which the unit-test policy prohibits, or an exclusion attribute, which AC20's own fourth clause prohibits.
• Synchronous QfcItemController.LoadFolderHandler never calls InitAsync (live).
• Duplicated MailItemHelper.FromMailItemAsync calls (live).
• Pre-existing 500-line overages: QfcCollectionController.cs 2336, QfcFormControllerTests.cs 792, QfcQueue.cs 505. All three shrank in this change; none crossed the limit because of it.
• The dormant post-display pre-filter is dead code (latent).
• AC11 and AC12 are in tension as authored; the code implements the only coherent reading.
• Two stale comments and one stale test docstring left by the remediation cycle (latent, documentation only).

Related context only. Issue #427 tracks the broader duplicate-scoring report and stays open after this merge, because this change delivers only the scoped consumer-side portion of it. Issues #233 and #446 are already in a closed state and appear here only as precedent that this change preserves. None of these three is affected by merging this pull request.

GitHub Auto-close

• Closes Bug: quickfiler-carry-folder-predictor-to-item-controller #678