feat: inject historical reference into MAF

[fabbrik]

Summary

Story 2.3, and the last of Epic 2. The loop closes: a run is captured, verified, reflected on, finalized, indexed — and a later agent receives it.

ExperienceContextProvider is a simple-tier AIContextProvider (Story 1.7 rejected TextSearchProvider: no confidence or applicability fields, and no timeout). The host adds it to ChatClientAgentOptions.AIContextProviders; the capture extension never builds those options, so injection is deliberately a separate type.

Per invocation it resolves a retrieval request, retrieves, selects within the record limit, re-checks every candidate against the same eligibility rules retrieval applies — status, confidence floor, expiry and required environment attributes — asks the host's InjectionDecision, then writes one delimited block.

• The payload names source, confidence, applicability, when the lesson was learned, its environment, and an evidence summary from the reflection. No attempts, tool calls, arguments, results or evidence detail ever appear.
• Limits drop whole records, never cut one: 8 records and 16 KB by default, both validated, every omission recorded with its reason.
• Nothing breaks the run. Empty, timed-out or failed retrieval means no context and a reported result; only the caller's own cancellation propagates.

On labeling

Labeling is hygiene, not a control, and the docs say so. The test that matters makes the model obey the injected instruction and emit a guarded tool call: ApprovalRequiredAIFunction means the tool body never runs. It asserts the boundary held, not that the model behaved.

Known limitation, now documented and pinned by a test

Injected blocks accumulate in a session's history: turn 2 carries the fresh block and turn 1's copy. So a record revoked between turns keeps being sent from the earlier block, and the byte budget bounds one invocation rather than a conversation. MAF filters a provider's input to external messages, so the provider cannot reliably detect its own earlier blocks. Use a fresh session per task when that matters.

Review

Three reviewers raised 35 findings; 34 fixed, 1 deferred (a batched by-IDs read for the re-check). The serious ones: the final check was narrower than the eligibility it claimed to re-apply; the session accumulation above; and nothing pinned the injected message's role, so a switch from User to System would have inverted the posture with every test green.

Test plan

• dotnet build --configuration Release: 0 warnings, 0 errors
• dotnet test --configuration Release: 680 of 680 pass (MAF 86, Core 382, Postgres 125, Vectors 43). Locally with TESTCONTAINERS_RYUK_DISABLED=true.
• One test per edge case through a real ChatClientAgent, plus the authorization test, a three-turn session test, cancellation, and a loop-closure test that captures and finalizes a run then receives its own lesson back.
• CI green

🤖 Generated with Claude Code