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.

Empirisk bekreftet 2026-07-26, ikke lenger bare utledet. Oppstrøms skriver generated på håndskrevet innhold. Verifisert her: generated: { by: human:jsmith@acme, at: 2024-01-15T10:00:00Z } (okf/bundles/acme_retail/metrics/gross-margin-legacy.md, en menneskeskrevet metrikkdefinisjon).

Konsekvensen gjelder uansett hvilken opsjon som vedtas: en implementasjon som utleder «er dette maskingenerert?» eller «eier vi denne fila?» fra at generated finnes, er feil under v0.2. Under O1/O2 må predikatet derfor være generated.by == <vår aktør> og ingest_manifest — aldri nøkkelens tilstedeværelse. Under O0 og O3 er poenget uten virkning, siden markøren vår da ikke deler navn med et oppstrømsfelt som brukes slik.

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 for generated. 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 (verifisert oppstrøms: generated: { by: reference_agent/gemini-2.5-pro, at: 2026-06-30T14:00:00Z }). :153 («additional frontmatter keys MAY follow») er heller ikke i veien. Ingen opsjon tvinger fram en rikere frontmatter-modell i specen.

Presisering 2026-07-26 (llm-ingestion-okf): setningen over er målt på generated alene, og skal ikke leses som at :158 overlever v0.2 i sin helhet. Det gjør den ikke. sources — et annet nytt v0.2-felt — er kanonisk en blokkliste, verifisert oppstrøms:

sources:
  - id: margin-standard
    resource: policies/margin-standard.md
    author: human:jsmith@acme

Den formen bryter :158 direkte. Det er utenfor V1, som bare gjelder generated, og DEFAULT-profilen emitterer ikke sources — men det er et reelt §5-spørsmål den dagen noen vil emittere v0.2s øvrige felter, og det er commons' å svare på. Ikke i køen, ikke meldt videre.

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.

Evidens FOR O1, tilført 2026-07-26. llm-ingestion-okf korrigerte sin egen anbefaling da de hadde lest oppstrøms' bundles og ikke bare SPEC.md: oppstrøms referanseimplementasjon bruker selv produsent/versjon-formen. Verifisert her, uavhengig: generated: { by: reference_agent/gemini-2.5-pro, at: 2026-06-30T14:00:00Z } (okf/bundles/acme_retail/metrics/gross-margin.md). <produsent>/<versjon> er altså ikke en avvikende lesning av §7 — det er den kanoniske formen for et verktøy, brukt av spec-eieren. O1 er dermed den v0.2-idiomatiske opsjonen, og O2 er det bevisste avviket fra idiomet. Funnet i §6 står uendret ved siden av dette: oppstrøms' bundles er utdata fra én agent, ikke delte konformansfiksturer, så de to fakta er ikke i motstrid. Det er nettopp byttet operatøren skal ta stilling til: v0.2-idiomatikk mot reproduserbar delt fasit.

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
Oppstrøms bruker selv <produsent>/<versjon>	okf/bundles/acme_retail/metrics/gross-margin.md	by: reference_agent/gemini-2.5-pro
Oppstrøms skriver generated på HÅNDSKREVET fil	…/gross-margin-legacy.md	by: human:jsmith@acme
sources er blokkliste, ikke inline flow	samme fil, sources:	- id: + 4 nøkler, flerlinjes → bryter :158
SPEC.md er endret ETTER v0.2-migreringen	okf-melding, deres pin 3fcbb9f	«v0.2-commiten» ≠ «dagens spec-tekst» — uverifisert av oss
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