portfolio-optimiser-commons/docs/plan/2026-07-26-v1-generated-felt-okf-v0.2.md

V1 — hvilken form skal generated ha i ingest-spec etter OKF v0.2?

Status: beslutningsunderlag for operatøren. Fire opsjoner med målt kostnad, ingen anbefaling. Utløst av llm-ingestion-okf (coord, 2026-07-26) som spør fordi authorship er vår: deres DEFAULT-profil staterer ingest-spec §5, og «ingen lokale spec-endringer» er deres stående non-goal.

Underlaget rører ingen spec-tekst. ingest-spec.md står uendret på bfa5a9b/9801d35.

Beslektet: 2026-07-25-amendment-underlag.md (køen av ratifiserbare punkter — V1 hører hjemme der hvis den ratifiseres), 2026-07-25-b1-nav-golden-normative-status.md (samme form).

---

1. Det som ikke er oppe til vurdering

• Ærlighetsregelen selv (ingest-spec.md:33-34, avledet av method-spec.md:26) er unwaivable. Alle fire opsjoner under oppfyller den. Spørsmålet er hvilken form merkingen har, aldri om den finnes.
• Eierskaps-stempelets funksjon (:70, :82): at re-materialisering bare rører egne filer, og at en kurert skriver avviser det komplette stempelet. Ingen opsjon svekker den regelen.
• ingested_at som eksplisitt påkrevd argument (:139-143). Ingen opsjon innfører wall-clock. Der at finnes, bindes den til ingested_at.
• Hastegrad. llm-ingestion-okf er ikke blokkert: deres v0.2-støtte kommer som en ny profil ved siden av DEFAULT, additivt. Ingenting her er en brannslukking.

2. Premissene, verifisert

llm-ingestion-okfs to påstander er kontrollert mot kilden, ikke overtatt:

• Oppstrøms: OKF v0.2 (GoogleCloudPlatform/knowledge-catalog, okf/SPEC.md) definerer generated: { by, at }, og generated.by er REQUIRED within generated, typet som en aktør per §7. Aktørkonvensjonen har tre former: <producer>/<version> for agenter og verktøy, human:<id> for en person, process:<id> for en automatisert prosess.
• Toleransen dekker det ikke. v0.2 sier at konsumenter «MUST NOT reject documents with unrecognized fields» og ikke skal avvise for manglende valgfrie felter eller ukjente nøkler. Ingen setning pålegger en leser å svelge en kjent nøkkel med feil type. llm-ingestion-okfs lesning holder.
• Historikken frikjenner valget. generated var ikke reservert i v0.1. Ingen innførte en defekt; v0.2 tok navnet etterpå.

Én forbeholdsrad: deres egen plan (okf-v0.2-alignment.md) slår fast at spec-en er lest på main — en gren, ikke en tag — og at «an enumeration read off a moving branch is a premise, not a fact». Vår kontroll traff samme bevegelige gren. Ingen frossen spec-tekst bør endres før oppstrømsversjonen er pinnet til en commit. Det gjelder O1, O2 og O3 likt.

3. generated bærer to laster i vår spec, ikke én

Dette er funnet som former underlaget, og grunnen til at opsjonssettet ikke er tre.

Nøkkelen opptrer 7 ganger som kontraktsreferanse, fordelt på fem seksjoner. De deler seg på to akser som ingen av dem navngir:

Last	Hvor	Hva den svarer på	Hvem leser den
Ærlighetsmarkør	§1 :34, §7 :214	«er dette maskingenerert?»	en leser/presentatør av bundelen
Eierskapspredikat	§3 :70, §3 :82, §11 :275	«hvilke filer eier ingest — og hva skal en kurert skriver avvise?»	materialiseringen og dør C

Oppstrøms generated { by, at } er provenance/attribusjon — den første lasten, ikke den andre. v0.2 har ingen skriveeierskaps-semantikk; feltet er valgfritt, konsument-skrivbart og fritt for enhver aksesskontrollmening.

Konsekvensen er ikke at feltet ikke kan bære begge, men at en opsjon som flytter eierskapspredikatet over på et oppstrømsdefinert felt må uttale det: predikatet går fra en literal-sjekk (generated == true) til en parse-og-match på et felt hvis grammatikk oppstrøms eier og fritt kan revidere. Konjunksjonen med ingest_manifest — vår egen nøkkel, ikke reservert oppstrøms i noen versjon — bærer fortsatt uforfalskbarhet-mot-uhell, så stempelet kollapser ikke. Men :82s «permitting either field alone» må omformuleres: under v0.2 vil kurert innhold legitimt kunne bære en generated-mapping med en helt annen by.

4. Spørsmålet

Skal generated i ingest-spec §5/§7 forbli den literale true, anta v0.2-formen { by, at } — og i så fall med hvilken aktørstreng — eller skal vår markør flytte til en nøkkel oppstrøms ikke eier?

5. Opsjonene, med målt kostnad

Kostnad er talt som kontraktslinjer som må skrives om av de 7 (:34, :70, :82, :152, :214, :275, :309).

Det som ikke koster noe i noen opsjon: §5s formkrav overlever uendret. Prefikset er «OKF line-oriented key: value» (:150) og «All values MUST be single-line» (:158) — v0.2s kanoniske form for generated er en inline flow mapping på én linje, så den er single-line og line-oriented allerede. :153 («additional frontmatter keys MAY follow») er heller ikke i veien. Ingen opsjon tvinger fram en rikere frontmatter-modell i specen.

O0 — la generated: true stå, dokumentér avviket

0 av 7 linjer. Ingen frossen tekst røres; ingenting går i ratifiseringskøen. Eneste tilføyelse er en merknad om at nøkkelen kolliderer med et v0.2-definert felt.

Kostnad: DEFAULT fortsetter å emittere en v0.2-definert nøkkel med v1-verdi. En v0.2-leser har ingen plikt til å akseptere den (§2). Kollisjonen forsvinner ikke — den venter.

Reverserbar. Ja.

O1 — v0.2-form med produsent-aktør (llm-ingestion-okfs anbefaling)

generated: { by: "llm-ingestion-okf/<versjon>", at: <ingested_at> }, predikatet utledet av generated.by.

5 av 7 linjer (:34, :70, :82, :214, :275). :152 og :309 navngir bare nøkkelen og overlever.

Denne opsjonen kolliderer med en eksisterende normativ setning — se §6. Kostnaden er ikke bare fikstur-regenerering.

Reverserbar. Nei — frossen normativ tekst.

O2 — v0.2-form med produsent-nøytral aktør

generated: { by: "process:<fast id>", at: <ingested_at> }. v0.2 §7 tillater eksplisitt process:<id> for en automatisert prosess (verifisert, §2). Aktøren navngir da prosessen specen definerer, ikke verktøyet som kjørte den.

5 av 7 linjer — nøyaktig samme som O1. Den eneste tekstlige forskjellen mot O1 er aktørstrengen; den avgjør til gjengjeld §6.

Kostnad: generated.by identifiserer ikke lenger hvilket verktøy som produserte filen. Produsent-identitet må da bo i implementasjonens egen logg. Om det er et tap eller et krav avhenger av §6.

Reverserbar. Nei.

O3 — døp om vår markør, la generated være fri

Vår markør flyttes til en nøkkel oppstrøms ikke eier; generated overlates til v0.2-semantikk.

7 av 7 linjer — også :152 (prefiks-lista) og :309 (kryss-sjekk-tabellen), fordi nøkkelen selv skifter navn. Dyrest i tekst.

Til gjengjeld: predikatet bevares eksakt som en literal-sjekk, aksene i §3 skilles ved konstruksjon, og kollisjonen kan ikke gjenoppstå ved neste oppstrømsrevisjon. v0.2 forbyr det ikke — de nye feltene er valgfrie oppstrøms.

Kostnad: interop-tapet er reelt. En v0.2-leser som spør «er dette maskingenerert?» via generated får ikke svar. Ærlighetsregelen er oppfylt internt, men ikke lesbar for formatets egne lesere — som er en del av hvorfor vi ligger i OKF i det hele tatt.

Reverserbar. Nei.

6. Funnet som omformer opsjonssettet (ikke en anbefaling)

O1 som formulert kolliderer med konformansleddet i §1.

• ingest-spec.md:29: en konform implementasjon MUST «reproduce the shared golden extractions (§11) byte for byte».
• ingest-spec.md:267: expected-bundle/ er «compared file by file, byte for byte».
• ingest-spec.md:280: sømmen Golden regression fyrer når «any byte of a golden extraction's expected bundle diverges».
• generated ligger i det obligatoriske ordnede prefikset (:149-152) — altså inne i de bytene.

Med by: "llm-ingestion-okf/<versjon>" bærer en delt fasit én produsents navn og versjonsnummer. Da følger to ting mekanisk:

1. Ingen annen konform implementasjon kan reprodusere fasiten byte for byte. Kravet i :29 gjelder enhver konform implementasjon, ikke den som lagde fikstursettet. Kravet blir uoppfyllbart ved konstruksjon for alle andre enn én.
2. Golden regression fyrer på hver versjonsbump av biblioteket — uten at noen kontrakt har endret seg. Sømmen slutter å måle det den er satt til å måle.

O2 unngår begge: aktørstrengen er da specens, ikke produsentens, og bytene forblir produsent-nøytrale. O0 og O3 berører ikke spørsmålet.

Merk hva funnet ikke er. Det er ikke et argument for O2 og mot O1 i seg selv. Operatøren kan gyldig svare at fasit-klassen aldri får mer enn én produsent, eller at generated skal ut av det byte-sammenlignede prefikset. Men da er det valget som må ratifiseres — funnet sier bare at O1 ikke kan vedtas uten samtidig å ta stilling til :29.

6.1 Rekkevidde-forbeholdet, korrigert 2026-07-26

Første utgave skrev at konflikten er «normativ, ikke observerbar — den utløses den dagen commons publiserer sin første ingest-fasit». Det var for snevert, og llm-ingestion-okf korrigerte det med en måling. Riktig bilde, etter kontroll i alle tre trær:

• examples/ingest-golden-* finnes fortsatt ikke i commons — og har aldri gjort det (git log --all -- 'examples/ingest-golden-*' → tomt).
• Men fikstursettene finnes hos implementasjonene, og generated ligger i bytene: fire filer hos llm-ingestion-okf, alle på :8, inne i prefikset. Del (ii) av funnet — at Golden regression (:280) ville fyre på hver versjonsbump — er derfor observerbar i dag, ikke i framtiden. Den utløses ved deres neste release.

6.2 Funnet under funnet: «the shared golden extractions» har ingen referent

Kontrollen for 6.1 avdekket noe som gjelder uavhengig av hele V1-spørsmålet, og som ingen har meldt:

Repo	examples/ingest-golden-*/expected-bundle/
commons	finnes ikke, har aldri funnes
llm-ingestion-okf	ingest-orders.md, ingest-products.md, ingest-metrics.md, ingest-status.md (+ 3 index.md)
portfolio-optimiser-claude	ingest-costs.md ×2, ingest-edge.md, ingest-meta.md (+ 2 index.md)

Overlappet i innholdsfiler er null. De eneste sammenfallende navnene er index.md, og de er byte-ulike (ulik oppsummering, ulike lenkemål — verifisert med cmp).

ingest-spec.md:29 krever at en konform implementasjon reproduserer «the shared golden extractions (§11) byte for byte». Bestemt form forutsetter ett sett. Det finnes to, begge lovlig navngitt etter konvensjonen i :259-260, ingen av dem publisert her. Konformansleddet er dermed ikke-testbart i dag — ikke fordi fasiten mangler, men fordi det er to av dem, og hver implementasjon reproduserer sin egen per konstruksjon.

Dette er et selvstendig punkt, ikke en del av V1, og det er ikke i køen. Det er tatt med her fordi det avgjør hvor tungt :29-argumentet i §6 veier: argumentet er ikke «dette bryter en delt fasit vi har», men «dette sementerer at en delt fasit aldri kan oppstå».

7. Det som ikke er commons' å avgjøre

• Hvilken opsjon som velges. Spec-teksten er frossen; endringer går gjennom ratifiseringskøen. V1 er punkt nummer 8 hvis den ratifiseres — den står utenfor de 7 i 2026-07-25-amendment-underlag.md og fortrenger ingen av dem.
• Hva llm-ingestion-okf gjør i sin egen v0.2-profil. Den er additiv og deres authorship. Bare DEFAULT staterer vårt lag.
• Om produsent-identitet skal logges et annet sted (O2s pris). Implementasjonens valg.

8. Det som ikke endres uansett utfall

Ærlighetsregelen, eierskapsstempelets funksjon, ingested_at-argumentet, §5s single-line- og line-oriented-krav, og ingest_manifest som stempelets andre halvdel. Ingen opsjon rører method-spec.md — nøkkelen forekommer ikke der (grep -c '\generated' method-spec.md` → 0).

---

Verifiseringslogg

Påstand	Sjekk	Resultat
v0.2 definerer generated: { by, at }	okf/SPEC.md @ main, hentet 2026-07-26	«generated: { by: reference_agent/gemini-2.5-pro, at: 2026-06-20T22:53:05Z }»
by er påkrevd	samme	«generated.by: REQUIRED within generated. An actor (§7).»
Aktørkonvensjonen har tre former	samme, §7	<producer>/<version> / human:<id> / process:<id>
timestamp er superseded	samme	«timestamp is superseded by generated.at»
Toleransen gjelder ukjente, ikke feiltypede	samme	«MUST NOT reject documents with unrecognized fields»; lista dekker manglende valgfrie + ukjente
Oppstrøms er lest på en gren, ikke en tag	llm-ingestion-okf/docs/plan/okf-v0.2-alignment.md	«main on 2026-07-26 — a branch, not a tag»
Kontraktsreferanser til nøkkelen	grep -n '\generated' ingest-spec.md`	7 linjer: :34 :70 :82 :152 :214 :275 :309
Nøkkelen finnes ikke i method-spec	grep -c '\generated' method-spec.md`	0
Ærlighetsregelen er unwaivable	ingest-spec.md:33-34, method-spec.md:26	«unwaivable» begge steder
Stempelet er generated: true + ingest_manifest	ingest-spec.md:70, :82	ordrett sitert over
Dør C avviser kun det komplette stempelet	ingest-spec.md:82-85	«while permitting either field alone»
generated ligger i det ordnede prefikset	ingest-spec.md:149-152	7 nøkler, generated er den sjuende
Prefikset er åpent bakover	ingest-spec.md:153	«additional frontmatter keys MAY follow it»
Single-line-kravet holder for flow mapping	ingest-spec.md:150, :158	«line-oriented key: value» / «All values MUST be single-line»
Konformans krever byte-lik delt fasit	ingest-spec.md:29	«reproduce the shared golden extractions (§11) byte for byte»
Fasiten sammenlignes byte for byte	ingest-spec.md:267, :280	«byte for byte» / «any byte … diverges»
Ingen ingest-fasit finnes i commons	ls -d examples/ingest-golden-*	ingen treff
…og har aldri funnes	git log --all -- 'examples/ingest-golden-*'	tomt
generated ligger i fasit-bytene hos okf	grep -rn '^generated' llm-ingestion-okf/examples/ingest-golden-*/expected-bundle/*.md	4 filer, alle :8
…inne i det ordnede prefikset	sed -n '1,9p' .../ingest-orders.md	7 nøkler :2-8, generated sist
Predikatet nøkler på literalen i dag	materialize.py:131-150	frontmatter.get("generated") != "true" + stem-match
To disjunkte fasitsett finnes	comm -12 over begge trærs expected-bundle/*.md	kun index.md-navn felles
…og de felles index.md er ulike	cmp på ingest-golden-file/.../index.md	ULIKE
§1 sier «the shared golden extractions»	ingest-spec.md:29	bestemt form, én mengde forutsatt
ingested_at har ingen wall-clock-default	ingest-spec.md:141	«there is NO wall-clock default»
Spec-tekst uendret siden 07-21	git log --oneline -- ingest-spec.md	bfa5a9b, forrige 7aa53fc — ingen commit etter