portfolio-optimiser/docs/plan/2026-07-03-program-brief-ingest-konnektorer.md

Program-brief: Ingest-lag — tools og konnektorer for reelle datakilder

Status: BRIEF, ikke plan. Skrevet 2026-07-03 på operatørs bestilling (fra D7-søskensesjonen, etter fullført S10). Dette dokumentet er input til et NYTT program; programmets to første leveranser er et målbilde-dokument og en gated sesjonsplan — begge lages i en egen planleggingssesjon i dette repoet (prompt nederst). Ingenting her er besluttet før den sesjonen har kjørt og operatør har godkjent.

1. Behovet (hvorfor programmet må finnes)

Begge stackene (MAF + D7/Claude Agent SDK) er bevist på kuraterte OKF-bundles (shared/examples/bygg-energi-mikro/). Praktisk anvendbarhet krever at fageksperter kan:

1. koble rammeverket til reelle datakilder (økonomisystem, prosjektdatabase, FDV-system, energimålere, dokumentarkiv), og
2. definere hvilke spørringer som henter underlaget per kjøring.

Dagens planverk (S1–S12) dekker ikke dette. Verifisert 2026-07-03: null forekomster av ingest/konnektor i sesjonsplanen; eneste spor er nordstjernens «MCP/RAG = extension point, ikke nå» (2026-06-26-maalbilde-agentic-loop.md §90%-prinsippet) samt de tekniske krokene som allerede finnes (build_mcp_server i MAF; @tool/create_sdk_mcp_server i Agent SDK, verifisert i D7-S5).

2. Arkitektonisk premiss (arvet fra metode-spec — ufravikelig)

• Data når modellen KUN via OKF-bundles. Metode-spec-en forbyr eksplisitt query-time retrieval-tools pekt mot bundelen: «never via a query-time retrieval tool pointed at the bundle (which would re-leak the verdict layer)». Konsekvens: konnektorer lever i et ingest-steg som kjører FØR optimalisereren og materialiserer uttrekket som en OKF-bundle. Ikke RAG, ikke live-oppslag i agent-løkka.
• Provenance helt tilbake til kilden. §9-citations peker i dag på fil + span i bundelen. Ingest-laget må stemple hver generert konseptfil med kilde-system, spørring og tidspunkt, slik at kjeden ekspert → forslag → bundle-fil → kildesystem er ubrutt.
• Lokal-only default, ingen stille egress. Kildekall er både kost og risiko; samme disiplin som D6 (tak, logging, eksplisitte kjøringer).
• Deterministisk kjerne røres ikke. Begge suitene skal fortsatt kjøre uten nøkkel og uten nettverk; konnektorer testes mot fixtures/golden-uttrekk, aldri mot levende kilder.
• Ærlighets-regelen (§1) gjelder også ingest-artefakter: en maskingenerert bundle merkes som det, med manifest-referanse.

3. Foreslått scope (til vurdering i målbildet — IKKE besluttet)

• Delt, stack-nøytral kontrakt i commons: et «ingest-manifest» (kilde, spørring, mapping → OKF-typer, provenance-krav) som spec — slik at begge stackene konsumerer samme format. Endres i commons, subtree-pulles (PULL-ONLY-regimet står).
• Referanseimplementasjon per stack: MAF (FunctionTool/MCP-søm) og D7 (in-process MCP / @tool).
• Kildetyper i prioritert rekkefølge: (a) filkatalog/CSV — null nettverk, bevis hele formatet offline først; (b) SQL/database; (c) HTTP/MCP-server mot eksterne systemer.
• Ekspertens spørringsdefinisjoner som konfig, ikke kode — validert fail-fast à la contracts.py, med operatør-gate før første kjøring mot en ny kilde.

4. Utenfor scope

• Ingen endring i agent-atferd eller nye modellkall — ingest er deterministisk.
• Ikke query-time retrieval/RAG (forbudt av metode-spec, se §2).
• DPIA/ROS/behandlingsformål eies fortsatt av deployer (rent teknisk rammeverk).
• Ingen endring i golden-fasiten eller eksisterende suite-invarianter.

5. Avhengigheter og rekkefølge

• Starter tidligst etter S11 (rapporten kan påvirke valg av primærstack for referanseimplementasjonen). S12 (release) er uavhengig og kan gå før eller etter.
• Commons-endringer følger PULL-ONLY; nye spec-avsnitt skrives i commons-repoet.

6. Programmets forventede leveranser

1. Målbilde-dokument (frossen nordstjerne for ingest-laget): arkitektur, kontrakter, sikkerhetsrammer, provenance-format.
2. Gated sesjonsplan i samme form som 2026-07-02-sesjonsplan.md (mål + innhold + verifisering per sesjon; operatør-gates ved repo-/spec-endringer og første live-kilde).
3. Deretter implementasjonssesjoner per plan.

7. Åpne spørsmål målbildet MÅ besvare

• Bor ingest-manifest-spec-en i method-spec.md (ny §) eller som egen spec i shared/?
• Provenance-format for kilde-stempling — utvidelse av §9 eller eget lag i frontmatter?
• Credential-håndtering (keychain-mønsteret; aldri i manifest/konfig).
• Inkrementell re-ingest vs. full re-materialisering; versjonering av bundles.
• Hvordan HITL-eksperten godkjenner et ingest-manifest før første kjøring (gate-mekanikk).
• Testabilitet: golden-uttrekk per kildetype slik at load-bearing-regelen (§11) også dekker ingest-sømmen.

Verifisering (for planleggingssesjonen som konsumerer denne briefen)

• Briefens premisser kontrollert mot shared/method-spec.md og nordstjernen FØR noe skrives (sitatene i §2 gjenfunnet ordrett).
• Målbilde-dok committet i docs/plan/ med retrieval-forbudet sitert og adressert.
• Sesjonsplan der HVER sesjon har mål + verifisering; første implementasjonssesjon er offline-kildetypen (filkatalog/CSV).
• Nøkkelantakelser testet eller merket som risiko: (1) en maskingenerert bundle passerer eksisterende OKF-robusthetsregler — test mot eksisterende OKF-kode med syntetisk bundle; (2) ingest-manifest kan valideres fail-fast uten nettverk.
• Suitene i begge repo fortsatt grønne uten nøkkel/nettverk etter evt. commons-pull.

Prompt for å starte programmet (kjør i DETTE repoet)

Les docs/plan/2026-07-03-program-brief-ingest-konnektorer.md. Dette er en
PROGRAM-PLANLEGGINGSSESJON for ingest-laget — den rører IKKE S11/S12-løpet.

1. Verifiser briefens premisser mot shared/method-spec.md og
   docs/plan/2026-06-26-maalbilde-agentic-loop.md (premiss-verifisering før handling).
2. Lag i plan-modus: (a) målbilde-dokument for ingest-laget, (b) gated sesjonsplan —
   begge per briefens §6 og verifiseringsliste. Presenter planen for godkjenning FØR
   noe committes.
3. Merk: STATE.md her er stale (NESTE peker på S6; S6–S10 er fullført i søskenrepoet,
   S10-artefakter ligger i dets runs/s10/). Reconcilier STATE ved sesjonsslutt, og
   fjern push-frys-linjen hvis operatør bekrefter at frysen er opphevet.