portfolio-optimiser/docs/2026-08-29-maf-gjelden-omfang.md

MAF-gjelden — omfang, ikke bygg (2026-08-29)

Ordre: 20260825T214801Z-2660820373-from-.claude, oppfølging av misjons-reviewen (25.08). Mandat: mål omfanget av fire funn — F3, F15, F16, U16/U17/U19 — og lever kost/risiko/gevinst + en anbefalt rekkefølge. Ingen kode er endret. Hvert tall under kommer fra en kommando kjørt i DENNE økten (verifiseringslogg § 6); der reviewens tall er sitert direkte, er det merket.

0. Ferskhets-korreksjon FØR noe annet — reviewens telling er fire dager gammel

Reviewen (25.08) talte 5 ja / 5 delvis / 9 nei av 19. Siden da har c08ae91 (26.08, «U12 + asynkron U13, rad 3») landet checkpoint-persistens i explore.py (checkpoint_storage= på _ALLOWED_CHECKPOINT_TYPES, bak --checkpoint-dir). Frisk grep i dag (§ 6, linje 1–19) flytter U12 fra nei til ja (opt-in):

Ny telling, 29.08: 6 ja (U3, U4, U6, U12, U14, U18) · 5 delvis (U7, U8, U9, U11, U13) · 8 nei (U1, U2, U5, U10, U15, U16, U17, U19). Av de åtte nei-radene er fem begrunnet i repoet (U1, U2, U5, U10, U15); tre er det ikke — nøyaktig U16, U17, U19, uendret fra reviewen, som er dette dokumentets fokus. Dette bekrefter at ordrens premiss («disse tre er uadresserte») fortsatt stemmer, men med et korrigert nevnertall — nok en instans av F12s advarsel («feil nevner har sirkulert»): selv reviewens eget tall råtner på fire dager.

1. F3 — ExpeLContextProvider er en MAF-hook som ikke bærer noe

Bekreftet uendret (linjenumre skiftet med commits siden 25.08, men koden og kommentarene er identiske i sak): run.py:789-792 kaller .format_fewshot() og string-konkatenerer inn i gen_context FØR generering — dette er det som faktisk når prompten. run.py:906-910 kjører ExpeLContextProvider(...).before_run(...) inn i en lokalt konstruert, kastet SessionContext etter at forslaget er generert — kommentaren sier det selv, ordrett: «this block's SessionContext is NOT what reaches the prompt» (run.py:905). Det andre kallet finnes utelukkende for å holde en regresjonsvakt i live (den to-argument extend_instructions-signaturen, «Critical Fase-1 GA-signature guard») — ikke for funksjon.

Hvorfor det er vanskeligere enn å «bare koble den til» (målt § 6, linje 20-22): context_providers er et konstruksjonsargument på Agent/ChatAgent (_agents.py:385/676/1740, også eksponert via BaseChatClient.create_agent(context_providers=...), _clients.py:577) — det er ikke et argument get_response() tar. generate_via_llm (generate.py:460) kaller derimot chat_client.get_response(...) direkte, uten noen Agent-wrapper. Å la MAF-hooken faktisk bære injeksjonen krever at proposer-kallet flyttes fra rå get_response() til chat_client.create_agent(context_providers=[...]).run(...) (eller tilsvarende) — en strukturell endring av selve kall-stien Step 5 bygger på, ikke en lokal one-liner.

Filer som røres	src/portfolio_optimiser/generate.py (kall-sti, strukturert-output-wiring, retry/refine-løkke), src/portfolio_optimiser/run.py:787-792/901-910 (fold + det dekorative kallet fjernes eller erstattes), src/portfolio_optimiser/verdicts.py (ExpeLContextProvider, mulig signaturendring)
Tester som må skrives/re-verifiseres	tests/test_step5_refine_loadbearing.py, tests/test_step5_history_loadbearing.py, tests/test_structured_output_loadbearing.py, tests/test_parse_failure_capture_loadbearing.py (alle fire hviler på generate_via_llms nåværende kall-form)
Oppgraderingsløp nødvendig?	Nei isolert — context_providers finnes i installert 1.9.0 (verifisert § 6, linje 23). Uavhengig av F15.
Risiko	MEDIUM-HØY. Rører den mest load-bearing løkka i repoet (budsjett-metering, strukturert-output-skjema, retry-historikk); en Agent-wrapper må bevise at den overflater SAMME usage/token-metadata TokenMeter leser i dag.
Gevinst	Injeksjonen blir en egenskap ved GRAFEN i stedet for ved run.pys prosa — det U9 faktisk ba om. Fjerner det dekorative kallet (mindre kode, ingen «ser brukt ut»-forkledning).
Kost, isolert	1,5–2,5 økter (Opus 5/xhigh, TDD). Se § 4 for hvorfor F3 og F16 bør bygges SAMMEN.

2. F15 — MAF-pinnen, re-verifisert EKSTERNT i dag (29.08, ikke 25.08)

Reviewens tall var allerede fire dager gammelt da den ble skrevet; mitt tall er fra i dag. PyPI (§ 6, linje 24-25): agent-framework-core siste er 1.16.0 (28.08 — GÅR I GÅR), ikke 1.15.0. Sekvensen siden 1.9.0: 1.10.0, 1.11.0, 1.12.0, 1.12.1, 1.13.0, 1.14.0, 1.15.0, 1.16.0. Repoet er altså SYV minor-releaser bak, ikke seks. agent-framework-orchestrations siste er 1.1.1 (21.08), og krever core<2,>=1.15.0 — orchestrations kan IKKE oppgraderes uten å ta core med seg; det finnes ingen delvis bump.

Ny, konkret ting reviewen ikke gjorde: jeg installerte 1.16.0 + orchestrations 1.1.1 i et isolert scratch-venv (/tmp, intet repo-treet berørt, slettet etter bruk) og diffet de to KONKRETE private-API-premissene test_maf_version_guard.py og explore.py navngir (§ 6, linje 26-31):

• _inner_get_response / _build_response_stream (agent_framework/_clients.py) — strukturelt uendret, kun linjeskift på +3 (227→230 osv.). Samme nøkkelord-signatur.
• explore.pys siterte _magentic.py:1118/:1128-1131 (speaker_known/next_speaker-fallback- blokken) — samme logikk, samme rekkefølge, linjeskift +10 (filen vokste fra 1805 til 1810 linjer). next_speaker not in self._participant_registry.participants — samme sjekk, samme sted relativt til resten av metoden.

Dette er en reell de-risking reviewen ikke hadde: de to konkrete tingene som gjør pinnen til en test-time tripwire (ikke bare en frys av bekvemmelighet) holder seg stabile over syv minor- releaser. assert_supported_maf_version (§ 6, linje 32) godtar for øvrig ALLEREDE 1.16.0 — guarden er en åpen range-sjekk (major == 1 and minor >= 9), ikke en eksakt pin; det er uv.lock som låser til nøyaktig 1.9.0, ikke testen.

Tre reelle breaking changes i vinduet (GitHub-releases, § 6, linje 33), rangert etter relevans for VÅR kode:

1. 1.13.0 (30.07): «Workflow checkpoints are now fully replayable from initial input and human-in-the-loop responses, requiring architectural adjustments.» Dette treffer DIREKTE c08ae91s checkpoint-wiring (explore.py:478-493/1611) — kode som er tre dager gammel relativt til en releasenote som endret akkurat det formatet. tests/test_async_plan_review_loadbearing.py (17 tester) må re-kjøres mot den nye formen FØR noen bump vurderes trygg.
2. 1.15.0 (21.08): OTel GenAI-konvensjonene konsolidert («stable and experimental modes with explicit message-event controls»). Treffer tracing.py (U14) og — fordi demoens pinnede stderr er en byte-fasit (P4) — potensielt tests/golden/demo-transcript.stdout/.stderr. tests/test_tracing_loadbearing.py (9 mutasjoner) må re-kjøres.
3. 1.15.0: MiddlewareFailure som nytt fatalt signal for function middleware. Lav risiko for oss (vi bruker ChatMiddleware/FunctionMiddleware til budsjett og observasjon, ikke til å blokkere), men bør sjekkes mot budget.py:228/mcp_tools.py:197.

Er begrunnelsen for pinnen fortsatt gyldig? Delvis. De to spesifikke private-API-premissene tripwiren finnes for, holder (målt i dag, ikke antatt). Det som IKKE lenger holder, er STATE.md:99s ordvalg «ENDELIG» — «endelig» beskriver en beslutning som ikke trenger re-evaluering; det denne målingen viser er at prisen for å UTSETTE fortsetter å vokse (syv releaser og stigende), mens selve oppgraderingsrisikoen på de to tingene som faktisk kan knekke oss, er lav og MÅLT lav. «Endelig» bør leses som «endelig for denne runden, re-vurder ved neste ordre», ikke som en frys uten utløpsdato.

Filer som røres	pyproject.toml (begge nedre grenser: agent-framework-core>=1.15.0, agent-framework-orchestrations>=1.1.0 el. l.), uv.lock (uv lock --upgrade-package agent-framework-core --upgrade-package agent-framework-orchestrations), tests/golden/demo-transcript.stdout/.stderr (mulig regenerering + manuell diff-gjennomgang), STATE.md/CLAUDE.md (pin-språket)
Tester som må skrives/re-verifiseres	Hele suiten (1080/5, ~200s) + spesielt tests/test_async_plan_review_loadbearing.py, tests/test_tracing_loadbearing.py, tests/test_maf_version_guard.py (bør IKKE trenge endring — se over)
Oppgraderingsløp nødvendig?	Ja, ETT sprang til 1.16.0 — orchestrations tvinger core≥1.15.0 uansett, så det finnes ingen billigere mellomstopp.
Risiko	MEDIUM. De to harde premissene er målt stabile; tre navngitte breaking changes treffer nylig bygget/skjørt kode (checkpoint 3 dager gammel, OTel byte-fasit). Ikke en rewrite, men heller ikke en formalitet.
Gevinst	Lukker syv-minor-gapet FØR det blir åtte/ni; fjerner den tyngste enkeltinnvendingen mot «eksperter på MAF»-påstanden; åpner orchestrations 1.1.1 (innhold ikke undersøkt her — egen sak); _compaction.py mister sine @experimental-dekoratorer i 1.16.0 (se § 4, U16 — mulig delvis relevant for U16, men Learn-dokumentasjonen kaller compaction fortsatt eksperimentell i prosa, så dette er IKKE en avklart «nå er U16 trygt» — kun et signal verdt å re-sjekke ETTER bump).
Kost, isolert	1–2 økter (Sonnet 5/xhigh for selve bumpen + re-kjøring; eskaler til Opus 5/xhigh hvis checkpoint- eller OTel-re-verifiseringen faktisk finner brudd).

3. F16 — B1-premisset er halvveis foreldet i INSTALLERT 1.9.0 (bekreftet, også i 1.16.0)

Bekreftet uendret, og bekreftet i BEGGE versjoner (§ 6, linje 34-35): class MiddlewareTermination finnes i agent_framework/_middleware.py UTEN @experimental-markør, i både installert 1.9.0 og scratch 1.16.0 (som i tillegg legger til MiddlewareFailure ved siden av den — samme ikke-eksperimentelle status). grep -rn "MiddlewareTermination" src/ gir 0 treff (§ 6, linje 3) — registerets U8 («intercept av tool-calls → blokkerende validator») beskrev nøyaktig denne formen; repoet har den ikke. Vår gate (validate_proposal, CBC + Monte Carlo + baseline- avstemming) kalles i dag ETTER generering, i run.py, utenfor grafen (P10-avgjørelsen).

Ordrens eget premiss («ikke et krav om å bygge om») stemmer, og det er viktig: dette funnet ber IKKE om at validatoren flyttes inn i middleware — det ber om at P10-avvisningen av «graf-adopsjon» re-vurderes MED dette premisset. Å faktisk flytte tall-gaten inn i middleware ville krevd nøyaktig samme forutsetning som F3 (proposer-kallet må gå via Agent/create_agent(), ikke rå get_response(), for at noen middleware-pipeline skal ha noe å hekte seg på) — F3 og F16 deler samme forutsetning-refaktor. De bør IKKE bestilles som to uavhengige jobber; en løsning som bygger den ene kall-sti-endringen løser forutsetningen for begge.

Kost — TIER 1 (bare re-vurdere P10, dokumentere)	Nær null. Én linje i STATE/CLAUDE.md: «P10 (avvis graf-basert validering) står, MEN premisset var 'MAF har ingen blokkerende-svar-primitiv' — det er nå delvis usant (MiddlewareTermination); beslutningen opprettholdes av en ANNEN grunn: validatoren trenger IR-parsing + solver + Monte Carlo, som ikke er en ting man vil kjøre synkront inne i response-middleware uten videre design.» Kan gjøres i denne leveransen om operatøren ønsker det — se § 5.
Kost — TIER 2 (faktisk bygge om)	Delt med F3s refaktor (se over). Isolert tillegg utover F3: src/portfolio_optimiser/validator.py-kallet må flyttes/wrappes som middleware, tests/test_checker_gate_loadbearing.py og tests/test_s40_cost_baseline_loadbearing.py må re-verifiseres mot den nye kall-formen.
Risiko	TIER 1: ingen. TIER 2: HØY — rører selve den «obligatoriske, blokkerende» invarianten (CLAUDE.md «Arbeidsflyt (invarianter)», første linje). Enhver regresjon her er alvorlig per repoets eget prinsipp.
Gevinst	TIER 1: ærlighet — P10 slutter å hvile på et utdatert premiss. TIER 2: «forslaget forlater aldri agenten uvalidert» blir en egenskap ved grafen, ikke ved run.pys disiplin — mer robust mot en fremtidig kalles feil, men samme FUNKSJONELLE utfall som i dag (suiten dekker begge like godt).
Kost, isolert	TIER 1: 0 økter (kan gjøres nå). TIER 2: bygg SAMMEN med F3 — se § 4s samlede anslag, ikke additivt.

4. U16/U17/U19 — uadresserte fordi ingen har sett, eller fordi de ikke passer?

Alle tre svares ut individuelt, per ordrens § 3 («et begrunnet 'nei' er et gyldig utfall»). To av de tre er små nok til at MÅLINGEN selv lukker raden (ordrens unntak) — gjort under, i dette dokumentet.

U17 — as_tool() (agent-som-verktøy): IKKE PASSER. LUKKES HER. Registerets egen kobling (§15.5 A3) knytter as_tool() til KRYSS-PROSJEKT agent-komposisjon («bruk in-process agent-as-tool først [for kryss-prosjekt], kun A2A ved sikkerhets-/compliance-grense»). Kryss-prosjekt er non-goal 2 i README («Not a portfolio-level reallocator … out of scope»). Uten kryss-prosjekt- komposisjon finnes det ingen naturlig bruksplass for «agent som verktøy for en annen agent» i denne arkitekturen — hvert prosjekt kjøres uavhengig. Vedtak: NEI, begrunnet, permanent (til non-goal 2 eventuelt oppheves — usannsynlig, det er en README-forpliktelse). 0 treff bekreftet (§ 6, linje 15).

U19 — Agent Harness: FORTSATT EKSPERIMENTELL, OGSÅ I 1.16.0. IKKE PASSER NÅ. LUKKES HER. Scratch-venv-diffen (§ 6, linje 36) viser @experimental(feature_id=ExperimentalFeature.HARNESS) på create_harness_agent, FileMemoryStore/_memory.py, _background_agents.py, _file_access.py — like mange markører i 1.16.0 som i 1.9.0. Reviewens observasjon («installert pakke sier selv [HARNESS] MemoryStore is experimental») er IKKE et 1.9.0-artefakt som forsvinner ved en bump — det holder seg over syv minor-releaser, i motsetning til Magentic (som MISTET sin eksperimentelle status og DERFOR ble tatt i bruk, § 3 i reviewen). Funksjonelt overlapper harness («bakgrunnsagent med fil-tilgang og løkke») med det utforskningssløyfa (explore.py, Magentic + checkpoint + plan-review) allerede gjør med et ANNET, ikke-eksperimentelt sett byggeklosser. Vedtak: NEI, begrunnet, for nå — revisit-utløser: harness mister @experimental-markøren PÅ NYTT målt, ELLER et konkret behov oppstår som Magentic+checkpoint ikke dekker (f.eks. en agent som må overleve utenfor request/response- syklusen helt, ikke bare over dager via checkpoint). 0 treff bekreftet (§ 6, linje 17).

U16 — Kontekst-kompaktering: EKTE GAP, INGEN HAR SETT PÅ DET. IKKE LUKKET, DEFERRED MED VILKÅR. I motsetning til U17/U19 er dette IKKE en «passer ikke»-sak. Lange Magentic-utforskningsløp (explore.py) har i dag KUN token-taket (ExplorationContract.max_tokens) som vern mot kontekstvekst — det er et KOST-tak, ikke et vindus-tak; en løkke kan i prinsippet nå modellens kontekstvindu-grense (avvisning fra API-et) FØR den når token-BUDSJETTET, og de to feiler ulikt (én er en strukturert BudgetExceeded, den andre er en rå leverandørfeil). Ingen levende utforskningskjøring har vart lenge nok til å utløse dette (F5: null validerte forslag mot levende modell), så det er ikke observert i praksis — men det er heller ikke DESIGNET bort. Python-API-en er compaction_strategy= på Agent-konstruksjon eller frittstående apply_compaction() (_compaction.py), IKKE C#-navnet CompactionProvider registeret bruker (F17 — feil navn, samme konklusjon). Kost til å lukke det EKTE gapet (ikke bare dokumentere fraværet): en design-beslutning om HVOR i Magentic-løkka kompaktering skal anvendes uten å miste frø-hypotesene (§ C.6 dør 1s bevaringsregel — kompaktering må aldri kunne kutte en frø-tilnærming), pluss ny wiring + tester. Vedtak: NEI, utsatt, begrunnelse skrevet ned HER (tilfredsstiller ordrens unntak for U-rader) — revisit-utløser: en --explore-kjøring mot en levende modell treffer et kontekstvindu-avslag, ELLER operatøren ønsker å bygge lange (>10 runder) utforskningsløp proaktivt. Kost hvis/når utløst: uestimert i dag — krever egen scoping-økt (design + § C.6-bevis), IKKE inkludert i totalanslaget § 5.

5. Anbefalt rekkefølge og ærlig totalanslag

1. F15 (versjonsbump 1.9.0→1.16.0). Gjøres FØRST fordi de to spesifikke tingene som kunne gjort den farlig, er nå MÅLT stabile (§ 2), og fordi hvert videre arbeid på F3/F16 uansett må re-verifiseres mot HVILKEN core-versjon som til slutt kjører — å bygge F3/F16 mot 1.9.0 først betyr dobbelt verifiseringsarbeid hvis F15 kommer etterpå. 1–2 økter.
2. F16 TIER 1 (re-vurder P10, dokumentér — kan gjøres NÅ, se under).
3. F3 + F16 TIER 2, bygget SOM ÉN JOBB (delt forutsetning: proposer-kallet flyttes fra rå get_response() til Agent-basert konstruksjon). Gjøres ETTER F15, slik at refaktoren skjer mot den versjonen som faktisk skal kjøre i produksjon. 2,5–4 økter (Opus 5/xhigh, TDD, høy testtetthet — anbefal adversarial review før commit gitt at dette rører den obligatoriske validator-invarianten).
4. U16 — ingen bygg nå; revisit ved utløser (§ 4). 0 økter i dag.
5. U17/U19 — LUKKET i dette dokumentet, ingen videre arbeid med mindre revisit-vilkårene inntreffer.

Totalanslag for det operatøren FAKTISK må velge å betale for: 3,5–6 økter (F15 + F3/F16 TIER 2). F16 TIER 1 og U17/U19 er reelt gratis — de er dokumentasjon, ikke bygg, og kan committes sammen med dette dokumentet uten å krysse ordrens «bygg ingenting»-grense (ingen kjørende kode eller pin røres).

Det jeg IKKE anbefaler: å bestille F3/F16 TIER 2 uten F15 først (dobbelt verifiseringsarbeid), og å bestille alle fire som én pakke (ordrens egen begrunnelse for hvorfor dette ble målt separat — ulik størrelse, ulik risiko — står; F15 er en ren versjons-øvelse, F3/F16 TIER 2 er et arkitektur-inngrep i den mest sensitive invarianten i repoet).

6. Verifiseringslogg (kommandoer kjørt i DENNE økten, 2026-08-29)

#	Påstand	Kommando → resultat
1-19	Fresh U1-U19 grep-tally	grep -rn <konstrukt> src/ per rad, § 0 — se full liste i øktloggen; U12 flyttet nei→ja siden c08ae91
20	Suiten grønn i dag	PYTHONIOENCODING=utf-8 uv run pytest -q → 1080 passed, 5 skipped, 2 warnings in 196.69s
21	Ingen kildeendring siden reviewen berører F3/F16/U16/U17/U19	git log --oneline 6020f44..HEAD → 3 commits (F2, katalogkall-kost, U12-checkpoint) — ingen treffer disse fem radene
22	pyproject/uv.lock pin	grep -n agent-framework pyproject.toml; grep -A1 'name = "agent-framework' uv.lock → core/orch/foundry/openai alle pinnet eksakt
23	F3 kodesti	sed -n '740,920p' src/portfolio_optimiser/run.py; grep -n "class ExpeLContextProvider|def before_run|extend_instructions" src/portfolio_optimiser/verdicts.py
24	context_providers kun på Agent, ikke get_response()	grep -n context_providers .venv/…/agent_framework/_agents.py (7 treff, alle på Agent/ChatAgent-konstruktør) vs. grep -n get_response src/portfolio_optimiser/generate.py (rå klientkall)
25	PyPI core siste versjon [ekstern]	WebFetch pypi.org/pypi/agent-framework-core/json → 1.16.0 (28.08); sekvens 1.10.0→1.16.0
26	PyPI orchestrations siste + dependency [ekstern]	WebFetch pypi.org/pypi/agent-framework-orchestrations/json → 1.1.1 (21.08), krever core<2,>=1.15.0
27	GitHub releases changelog 1.13-1.16 [ekstern]	WebFetch github.com/microsoft/agent-framework/releases → breaking changes sitert § 2
28-31	Scratch-venv privat-API-diff	uv venv /tmp/maf-scratch-1160 --python 3.12; uv pip install --python … "agent-framework-core==1.16.0" "agent-framework-orchestrations==1.1.1"; grep -n _inner_get_response|_build_response_stream mot begge versjoner av _clients.py; sed -n '1110,1135p' mot begge versjoner av _magentic.py; scratch-venv slettet etter bruk (rm -rf /tmp/maf-scratch-1160)
32	Versjonsguarden godtar 1.16.0 allerede	Lest tests/test_maf_version_guard.py:assert_supported_maf_version — major == 1 and minor >= 9, ingen øvre minor-grense
33	Tre breaking changes identifisert	Samme GitHub-fetch som # 27, kryssjekket mot explore.py/tracing.py/budget.py
34	F16: MiddlewareTermination i 1.9.0	grep -rn MiddlewareTermination src/ → 0 treff; grep -n "class MiddlewareTermination|@experimental" .venv/…/agent_framework/_middleware.py
35	F16: MiddlewareTermination i 1.16.0	Samme grep mot scratch-venv → identisk status (ikke eksperimentell), pluss ny MiddlewareFailure
36	U19: harness eksperimentell i 1.16.0	grep -rn "@experimental" scratch-venv/…/agent_framework/_harness/*.py → 16 treff, samme mønster som 1.9.0

Ikke verifisert i denne økten: innholdet i orchestrations 1.1.0/1.1.1 utover changelog- overskriftene (egen sak om operatøren vil vite HVA som vinnes der utover selve versjonstvangen); hvorvidt _compaction.pys manglende @experimental-dekoratorer i 1.16.0 betyr at Microsoft Learn- dokumentasjonens «currently experimental in Python»-advarsel (sitert i reviewen § 3.1) er utdatert eller om den fortsatt gjelder på et annet nivå (prosa vs. kode) — nevnt som åpent i § 4, ikke avgjort her; hvorvidt en faktisk 1.16.0-bump ville endret golden-transkriptets byte-fasit (krever å faktisk kjøre demoen mot den bumpede pinnen, som er byggearbeid utenfor denne ordren).