portfolio-optimiser/docs/plan/2026-07-03-maalbilde-ingest-lag.md

Målbilde — ingest-laget (tools og konnektorer mot reelle datakilder)

Status: KONSENSUS-forslag skrevet 2026-07-03 fra program-briefen — blir frossen nordstjerne for ingest-programmet når operatøren godkjenner det. Endres deretter bevisst, aldri ved drift (samme regime som hovednordstjernen). Fase-nivået er sesjonsplanen for ingest.

Provenance: arkitekturvalgene her (svarene på briefens §7-spørsmål) er AI-anbefalinger, adversarial-reviewet i planleggingssesjonen 2026-07-03; de er ikke bindende før operatør-godkjenning og kan overstyres punkt for punkt.

---

0. Hva dette dokumentet er (og ikke er)

Målbildet for hva ingest-laget skal være når det er sant — ikke en faseplan. Det definerer «ferdig» for programmet; sesjonsplanen sekvenserer veien dit. Ingest-laget er et tillegg foran den eksisterende 8-stegs-loopen: ingenting i dette dokumentet endrer metode-spec-en, golden-fasiten eller agent-atferden.

1. Behovet

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 — som konfig, ikke kode.

2. Arkitektur — ingest-steget kjører FØR optimalisereren

Metode-spec-en (§3 Steg 1) forbyr eksplisitt query-time retrieval mot bundelen:

«never via a query-time retrieval tool pointed at the bundle (which would re-leak the verdict layer)»

Konsekvensen er arkitektur-definerende: data når modellen KUN via OKF-bundles. Konnektorer lever derfor i et deterministisk ingest-steg som kjører før optimalisereren og materialiserer uttrekket som en OKF-bundle. Ikke RAG, ikke live-oppslag i agent-løkka, ingen retrieval-tools i kjørestien.

manifest → konnektor → mapping → OKF-bundle (inkl. index-generering) → [eksisterende loop, uendret]

Index-generering er del av kontrakten. En bundle uten index.md er en feil, og navigasjonen følger KUN index-cross-links (metode-spec Steg 1) — en generert konseptfil uten index-lenke er unåbar. Konnektoren genererer/oppdaterer derfor index.md (sammendrag + én lenke per generert fil); navigerbarhet er et load-bearing-krav (§9), ikke en detalj.

flowchart LR
    subgraph SRC["KILDESYSTEMER · aldri i agent-løkka"]
        ERP["Økonomisystem"]
        DB["Prosjektdatabase"]
        FDV["FDV / energimålere"]
        DOC["Dokumentarkiv"]
    end

    MAN["Ingest-manifest<br/>kilde + spørringer + mapping<br/>KONFIG, skjema-validert fail-fast"]

    subgraph ING["INGEST-STEG · deterministisk · kjøres eksplisitt (HITL-gate)"]
        CONN["Konnektor<br/>filkatalog/CSV · SQL · (HTTP/MCP)"]
        MAT["Materialisering<br/>provenance-frontmatter + index-generering"]
        CONN --> MAT
    end

    BUNDLE["OKF-bundle<br/>generert lag (ingest-eid)<br/>+ kuratert/promotert lag (urørt)"]

    LOOP["8-STEGS-LOOPEN<br/>uendret — leser bundelen<br/>via navigasjon, aldri retrieval"]

    SRC --> CONN
    MAN --> CONN
    MAT --> BUNDLE
    BUNDLE --> LOOP

3. Lag-separasjon i bundelen (ufravikelig)

Bundelen er ikke bare input — den er også wikien Steg 8 promoterer godkjent kunnskap inn i. To regler holder ingest og læringssløyfe adskilt:

• Verdict-laget er RESERVERT. Manifest-mapping MÅ IKKE produsere type: verdict-filer eller filnavn i promoted-verdict-*-navnerommet. Promoterings-gaten (metode-spec §6) er ENESTE vei inn i verdict-laget; Steg 1 seeder hver type: verdict-fil inn i store med decision-default approved, så en ingest som kunne skrive verdict-typede filer ville injisere maskingenererte «godkjente» dommer utenom gaten — nøyaktig selv-forurensningen gaten finnes for å hindre. Håndheves fail-fast i manifest-valideringen + load-bearing test.
• Ingest eier kun sine egne filer. Re-materialisering erstatter NØYAKTIG filene som bærer ingest-stempelet (generated: true + ingest_manifest-ref) og rører ALDRI kuraterte eller promoterte filer. Index-oppdatering er idempotent og bevarer kuraterte lenker (gjenbruker link_in_index-mønsteret i okf.py). Load-bearing: re-ingest over en bundle med promotert verdict → verdicten og dens index-lenke overlever.

4. Ingest-manifestet (kontrakten)

Ekspertens kobling til en kilde er ett JSON-manifest: kilde (type + tilkoblingsreferanse), spørring(er), mapping → OKF-typer (minus de reserverte, §3) og provenance-krav. Skjema-validert fail-fast à la contracts.py — et malformet manifest starter aldri en kjøring. Spørringene er KONFIG, ikke kode.

Credentials aldri i manifestet (svar på åpent spm. 3): manifestet bærer kun en referanse ved navn (env var / keychain-mønsteret); hemmeligheten slås opp ved kjøretid. Manifestet er dermed versjonerbart og delbart uten hemmeligheter.

Skjemaet designes polymorft for de tre kildetypene (filkatalog/CSV, SQL, HTTP/MCP) i én spec-runde — HTTP/MCP-delen holdes til et minimum (nok til at extension-point-demoen ikke trenger spec-endring, ikke mer) — slik at implementasjonsøktene ikke utløser spec-endringer.

5. Provenance — eget lag, ubrutt kjede (svar på åpent spm. 2)

Ingest-provenance er et eget frontmatter-lag på genererte konseptfiler — IKKE en utvidelse av metode-spec §9:

source_system: <kildesystem-id>
source_query: <spørringen som hentet innholdet>
ingested_at: <eksplisitt timestamp — se regelen under>
ingest_manifest: <manifest-ref/hash>
generated: true

Begrunnelse: §9 er proposal-provenance (forslag → bundle-fil + span); ingest-provenance er neste ledd i kjeden (bundle-fil → kildesystem). To separate kontrakter som aldri blandes — samme disiplin som de to falsifisererne. OKF-spec-en garanterer at egendefinerte felt bevares av konsumenter (verifisert mot eksisterende okf.py med syntetisk bundle, 2026-07-03).

• Timestamp-regelen: ingested_at er et EKSPLISITT PÅKREVD argument til materialiseringen — ingen wall-clock-default (speiler promoterings-gatens regel, metode-spec §6). Dermed er golden-uttrekk bit-deterministiske.
• Kjede-integritet: kjeden ekspert → forslag → bundle-fil+span → kilde+spørring+tidspunkt holder GITT versjonerte bundles (OKF-premisset: kuratert, versjonskontrollert). En re-materialisering er en ny bundle-versjon, og bundelen bærer materialiserings-stempelet (manifest-hash + ingested_at), slik at en kjørings citations kan knyttes til den konkrete materialiseringen. Versjonering av bundles er en dokumentert deployer-forutsetning — vi påstår ikke «ubrutt» utover den.
• Ærlighets-regelen (§1): en maskingenerert bundle MERKES som det (generated: true + manifest-ref) overalt der den presenteres.

6. Sikkerhetsrammer

• Lokal-only default, ingen stille egress. Nettverkskilder krever et eksplisitt opt-in-flagg per kjøring; uten flagg nekter konnektoren fail-fast.
• Kildekall logges (hvilken kilde, når, radantall) — samme disiplin som D6.
• Tak på uttrekksstørrelse (fail-fast ved overskridelse — aldri stille trunkering).
• DPIA/ROS/behandlingsformål eies fortsatt av deployer (rent teknisk rammeverk).

7. HITL-gate for manifestet (svar på åpent spm. 5)

MVP-mekanikken er to lag:

1. Prosessuelt: ingest kjøres ALDRI automatisk — alltid en eksplisitt operatør-/ ekspert-kommando med manifest-sti. Ingen scheduler, ingen implisitt re-ingest.
2. Teknisk: fail-fast skjemavalidering før noe kildekall + nettverkskilder nekter uten eksplisitt flagg (§6).

Rikere godkjenningsmekanikk (signert approved_by, godkjennings-register e.l.) er et extension point — ikke MVP (90 %-prinsippet).

8. Re-ingest og versjonering (svar på åpent spm. 4)

MVP = full re-materialisering av de ingest-eide filene per kjøring — deterministisk gitt samme kilde + manifest + timestamp, idempotent, og innenfor lag-separasjonen i §3 (kuratert og promotert innhold overlever ALLTID). Bundelen stemples med manifest-hash + timestamp. Inkrementell re-ingest er et extension point, ikke MVP.

9. Determinisme og testbarhet (svar på åpent spm. 6)

Konnektorer testes KUN mot fixtures/golden-uttrekk — aldri mot levende kilder. Golden-formatet er: fixture-kilde + fast timestamp → forventet bundle, bit-deterministisk. Suitene i begge repo kjører fortsatt uten nøkkel og uten nettverk.

Load-bearing-krav (testen MÅ bli rød når sømmen detaches — metode-spec §11-regimet):

1. Provenance-stempling detached → rød.
2. Generert bundle er navigerbar via uendret okf.py (inkl. index-lenkene) → rød hvis ingest genererer noe OKF-koden ikke tåler.
3. Verdict-reservasjonen (§3): manifest som mapper til type: verdict → avvist; rød uten reservasjonen.
4. Re-ingest bevarer promotert innhold (§3) → rød hvis re-materialisering sletter wikien.
5. Golden-uttrekk per kildetype → rød ved enhver drift i materialiseringen.

10. Spec-plassering (svar på åpent spm. 1)

Kontrakten bor i en egen spec: shared/ingest-spec.md i commons — IKKE som ny § i method-spec.md. Begrunnelse: metode-spec-en er normativ på loopen, frosset og beskyttet av spec-integrity-testen; ingest er et separat steg FORAN loopen; en egen fil holder frysingen intakt og lar begge stackene konsumere kontrakten uavhengig. Skrives i commons-repoet og subtree-pulles (PULL-ONLY-regimet står). Framework-guardene i BEGGE repo må EKSPLISITT utvides til å dekke den nye fila — verifisert 2026-07-03: dagens guard itererer kun metode-spec-en + skill-treet og dekker IKKE en ny spec-fil automatisk.

11. Stack-mapping (ærlighets-avgrenset)

• Delt (commons): ingest-spec + golden-uttrekk. Ren data/spec — framework-nøytral.
• Implementert i BEGGE stacker: filkatalog/CSV og SQL (sqlite-fixture). MAF gjenbruker contracts.py-mønsteret + okf.py-skriverne; D7 bygger egen impl mot samme spec.
• HTTP/MCP: demonstrert som extension point KUN på MAF-siden (mot lokal mock, gated bak nettverksflagget). D7s tekniske kroker (create_sdk_mcp_server, verifisert i D7-S5) dokumenteres som pekere — ingen D7-HTTP-økt planlegges.
• Ingen live-kilde forekommer noensinne i programmet. Briefens «første live kilde»-gate forblir ukonsumert — reservert deployer/framtidig arbeid. Sies eksplisitt her for at ingen artefakt skal kunne påstå live-integrasjon.

12. Utenfor scope

• Ingen endring i agent-atferd eller nye modellkall — ingest er deterministisk (null modellkall i hele programmet).
• Ikke query-time retrieval/RAG (forbudt av metode-spec-en, sitert i §2).
• DPIA/ROS/behandlingsformål eies av deployer.
• Ingen endring i golden-fasiten eller eksisterende suite-invarianter.
• Ingen scheduler/orkestrering av ingest-kjøringer (deployers ansvar).
• Ingen live-kilder (§11).