docs(plan): program-brief for ingest-lag — tools/konnektorer mot reelle datakilder
Brief (ikke plan) for nytt program etter S11: ingest-steg som materialiserer kildeuttrekk til OKF-bundles (metode-spec forbyr query-time retrieval i løkka), delt manifest-kontrakt i commons, referanseimplementasjon per stack. Inkluderer oppstartsprompt for planleggingssesjonen. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QdSfQdND84oeq2mbjueLTS
This commit is contained in:
parent
e4cbcae0c0
commit
aec95eb0da
1 changed files with 110 additions and 0 deletions
110
docs/plan/2026-07-03-program-brief-ingest-konnektorer.md
Normal file
110
docs/plan/2026-07-03-program-brief-ingest-konnektorer.md
Normal file
|
|
@ -0,0 +1,110 @@
|
|||
# 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.
|
||||
```
|
||||
Loading…
Add table
Add a link
Reference in a new issue