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

# Sesjonsplan — ingest-programmet (2026-07-03)

> **Hva dette er:** Program-nivåets øktkart for ingest-laget, avledet av
> [målbildet for ingest](2026-07-03-maalbilde-ingest-lag.md) (nordstjernen dette planverket
> realiserer) og [program-briefen](2026-07-03-program-brief-ingest-konnektorer.md). Målbildet
> definerer «ferdig»; denne planen sekvenserer veien. Hver økt er scoped til å **fullføres
> innenfor én sesjon**. Programmet starter først etter operatør-godkjenning av målbildet.

## Rammer (gjelder alle økter)

- **Modell:** Fable 5 med xhigh reasoning effort — global default; 2026-07-02-planens
  Opus-direktiv var scoped til dén planen og gjelder ikke her.
- **Én økt = én lukket leveranse:** grønn suite, STATE.md overskrevet, commit + push til
  Forgejo før økta slutter. Aldri broken state over en øktgrense.
- **Kode-økter:** stram Plan-modus + TDD (Iron Law: ingen produksjonskode uten rød test
  først). Hver økt får egen `/trekbrief` som kan re-scope innenfor «én økt = én lukket
  leveranse».
- **Kostnadsdisiplin (D6):** ALT offline — null modellkall i hele programmet (ingest er
  deterministisk; konnektorer testes kun mot fixtures/golden-uttrekk).
- **Commons PULL-ONLY:** spec-endringer skrives i commons-repoet og subtree-pulles. **Enhver
  commons-/spec-endring utover I1 er en egen GATET runde — aldri foldet inn i en impl-økt.**
- **Operatør-gates:** I1 (spec-/commons-endring), I3 og I5 (søskenrepoet røres), I6
  (nettverks-kapabilitet innføres). S12 (release) er uavhengig av dette programmet og forblir
  gated på egne vilkår.

## Avhengigheter

I1 → I2 → I3 → I4 → I5 → I6 → I7. (I6 avhenger teknisk kun av I2, men kjøres lineært etter I5
— enklere statehåndtering. I7 sist, avhenger av alle.)

---

## I1 — Ingest-spec i commons **[GATET: spec-/commons-endring]**

**Mål:** Den framework-nøytrale kontrakten eksisterer i commons og er guardet i dette repoet —
begge stackene kan implementere fra spec alene.

**Innhold:**
1. I COMMONS-repoet: forfatt `shared/ingest-spec.md` (framework-nøytral prosa — samme regel
   som method-spec): polymorft manifest-skjema for alle tre kildetyper (HTTP/MCP-delen som
   minimum, jf. målbildet §4), credential-referanse-regelen, verdict-lag-reservasjonen +
   lag-separasjonen (målbildet §3), provenance-frontmatter-kontrakten inkl. eksplisitt
   timestamp-argument (§5), index-genereringskravet (§2), golden-uttrekk-formatet (§9);
   kryss-sjekk-tabell felter ↔ avsnitt.
2. I DETTE repoet: `git subtree pull --prefix=shared commons main --squash` + utvid
   framework-guarden (`tests/test_method_spec_loadbearing.py`) til å dekke den nye fila.

**Verifisering:** guard-utvidelsen bevist RØD mot en throwaway-kopi med framework-navn
injisert · begge repos suiter grønne etter pull (søskenets pull kan tas i I3 hvis søskenrepoet
ikke røres i I1 — da gjelder «begge grønne» fra I3) · kryss-sjekk-tabellen komplett ·
`uv run ruff check .` + `mypy` grønne.

## I2 — MAF-referanseimplementasjon: filkatalog/CSV (offline)

**Mål:** Første implementasjonsøkt er offline-kildetypen (brief-krav): manifest → CSV-konnektor
→ materialisert OKF-bundle, hele veien load-bearing-testet. Lukker nøkkelantakelse 2.

**Innhold:** manifest-kontrakt (pydantic, fail-fast, uten nettverk), CSV-/filkatalog-konnektor,
materialisering → OKF-bundle med provenance-frontmatter + index-generering. TDD.

**Verifisering:** golden-uttrekk-test (fixture + fast timestamp → forventet bundle,
bit-deterministisk) · load-bearing: provenance-detach → rød; generert bundle navigerbar via
UENDRET `okf.py` → rød ellers (varig versjon av planleggingsøktas ad hoc-bevis); manifest som
mapper til `type: verdict` → avvist (rød uten reservasjonen); re-ingest over bundle med
promotert verdict → verdicten + index-lenken overlever (rød ellers) · suite grønn uten
nøkkel/nettverk · mypy/ruff grønne.

## I3 — D7-speil: filkatalog/CSV **[GATET: annet repo]**

**Mål:** Samme kontrakt konsumert uendret fra commons i søskenrepoet
(`/Users/ktg/repos/portfolio-optimiser-claude`) — beviser at ingest-spec-en faktisk er delt.

**Innhold:** forankres i søskenets STATE + egen `/trekbrief`. Commons-pull der; egen impl mot
samme spec; speiltester av I2s load-bearing-sett; søskenets framework-guard utvides
tilsvarende. Re-verifiser SDK-kroker søk-først (API-drift-risiko).

**Verifisering:** golden-uttrekk bit-identisk konsumert · speiltester røde ved detach ·
søskensuite grønn uten nøkkel/nettverk.

## I4 — SQL-kilde MAF (sqlite-fixture, null nettverk)

**Mål:** Andre kildetype på MAF-siden, mot I1-skjemaet uten spec-endring.

**Innhold:** sqlite-konnektor mot det polymorfe manifest-skjemaet. Ingen spec-endring
forventet; hvis drift likevel oppdages: egen GATET commons-runde FØR økta fortsetter
(ramme-regelen).

**Verifisering:** som I2 for SQL: golden-uttrekk (fixture-db + fast timestamp →
bit-deterministisk bundle) · load-bearing-settet · suite grønn uten nøkkel/nettverk.

## I5 — SQL-kilde D7-speil **[GATET: annet repo, som I3]**

**Mål/Innhold:** speiler I4 i søskenrepoet.

**Verifisering:** som I3 for SQL.

## I6 — HTTP/MCP som demonstrert extension point, MAF-only **[GATET: nettverks-kapabilitet innføres — lokal mock, ingen live-kilde]**

**Mål:** Extension-point-mønsteret demonstrert ærlig: HTTP/MCP-konnektor mot LOKAL mock,
gated bak opt-in-nettverksflagget. Ingen live-kilde — briefens «første live kilde»-gate
forblir ukonsumert i hele programmet (målbildet §11).

**Innhold:** lokal mock i test (in-process/localhost, bak flagget); dokumentér mønsteret i
`docs/extending.md` med D7-krok-pekere (`create_sdk_mcp_server`).

**Verifisering:** uten flagg → fail-fast nekt (rød hvis gaten detaches) · suite grønn HELT
uten nettverk · ingen artefakt påstår live-integrasjon (grep).

## I7 — Program-avslutning: dokumentasjon + statusrapport

**Mål:** Alt dokumentert sannferdig; programmet lukket med rapport.

**Innhold:** README/`docs/extending.md`-oppdatering i begge repo — der D7-omtalen AVGRENSES
til det D7 faktisk har (CSV + SQL; HTTP/MCP kun pekere); kort norsk statusrapport (hva er
bevist / ikke bevist — ærlighets-regelen).

**Verifisering:** verifiseringslogg i rapporten (hver påstand → kommando/kilde) · grep-sjekk:
ingen artefakt påstår HTTP/MCP-støtte i D7 eller live-kilde-integrasjon · begge repos suiter
grønne.

---

## Nøkkelantakelser (med eksplisitt test)

1. **Maskingenerert bundle passerer eksisterende OKF-kode** → testet ad hoc 2026-07-03
   (syntetisk bundle med provenance-frontmatter gjennom `navigate_bundle`/`bundle_context`:
   ukjente felt bevart, kontekst rendret). Efemert bevis — den VARIGE load-bearing-testen
   skrives i I2.
2. **Ingest-manifest kan valideres fail-fast uten nettverk** → antakelse med belegg
   (`contracts.py`-mønsteret er ren in-process), merket RISIKO til I2 lukker den med varig
   test (rød på malformet manifest, null nettverk).
3. **Commons-subtree-flyten fungerer** → bevist i S4 (PULL-ONLY-regimet etablert og dokumentert).
4. **D7s tekniske kroker dekker behovet** (`@tool`/`create_sdk_mcp_server`) → verifisert i
   D7-S5 per briefen; re-verifiseres søk-først i I3 (API-drift-risiko).

## Verifisering (planen som helhet)

- Ingen økt erklæres ferdig uten at øktas verifiseringskriterier er kjørt og grønne.
- Program-sluttkriterium: begge stacker materialiserer identiske golden-uttrekk fra delt spec
  (CSV + SQL); HTTP/MCP demonstrert MAF-only mot mock; alle load-bearing-krav i målbildet §9
  bevist røde ved detach; begge repos suiter grønne uten nøkkel/nettverk — og ingen artefakt
  påstår mer enn koden gjør (live-kilder, D7-HTTP, LLM-atferd).