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.
```