75: Implement the Nenjim Journal model, text parser, manager and filesystem service

docs/Nenjim.md

@@ -1,5 +1,9 @@
 #<center><H1>Nenjim<br>Documentation</H1></center>
 
+> **Dokumentstatus:** Journal-format version 1, den immutable Java-model, den interne tekstparser, det read-only
+> `JournalService` og den eksplicit refresh-baserede `JournalServiceManager` er implementeret. Afsnit 8–9 beskriver fremtidig vision og er ikke
+> funktionalitet i den nuværende Journal-implementation.
+
 **Indholdsfortegnelse:**
 <!-- TOC -->
   * [1. Introduktion til Nenjim](#1-introduktion-til-nenjim)
@@ -14,68 +18,173 @@
 <!-- TOC -->
 
 ## 1. Introduktion til Nenjim
-Nenjim er et innovativt system, der gør det muligt at håndtere forskellige versioner af softwarepakker simultant.
-Systemet løser udfordringen med afhængigheder og versionering ved at benytte unikke versionsnumre i pakkernes
-navngivning, hvilket sikrer, at flere versioner af samme softwarepakke kan eksistere side om side uden konflikter.
+Nenjim skal på sigt kunne håndtere forskellige versioner af softwareartifakter samtidigt. Det nu implementerede
+fundament er Journal-laget: et strengt tekstformat og en immutable model, som kan fastholde, hvad der var kendt om
+en artifakt på et bestemt tidspunkt. Dependency-resolution, Contexts, downloading og classloading kommer senere.
 
 ## 2. Versionering og Afhængigheder
-Nenjim bruger en metode, hvor pakker navngives med versionsnummer direkte i pakkenavnet. Dette håndteres dog i
-såkaldte journaler, udenfor selve koden, således at Java koden ikke har afhængigheder til Nenjim her.
-Dette sikrer, at udviklere ikke behøver at bekymre sig om versionskonflikter, da hver afhængighed refererer præcist
-til den version, den har brug for. Systemet sørger for, at alle nødvendige moduler er tilgængelige og opdaterede
-i baggrunden.
+Nenjim beskriver moduler, artifakter, releases, relationer og versionspolitik i Journaler. Almindelig Java-kode skal
+ikke indbygge Nenjim- eller versionsspecifikke navne for at bruge et API. Et Context beskriver de ønskede valg, og
+Nenjim resolver senere disse valg og Journalernes metadata til en eksakt artifakt- og dependency-graf.
+
+### 2.1 Én Journal per artifakt
+
+En Journal beskriver præcis én artifakt. API, tests og referenceimplementation har derfor hver sin Journal; roller
+som `API`, `IMPLEMENTATION` og `TEST` gemmes ikke som et `TYPE`-felt. Journalens identitet udledes af metadata:
+
+```text
+<GROUP>-<MODULE>-<ARTIFACT>
+```
+
+Eksempelkoordinater er `com_r35157_nenjim-hubd-api`, `com_r35157_nenjim-hubd-tests` og
+`com_r35157_nenjim-hubd-impl_ref`. En komplet release-reference tilføjer en eksakt Semantic Version:
+
+```text
+com_r35157_nenjim-hubd-api:1.0.3
+```
+
+Der findes intet separat `JOURNAL_ID`.
+
+### 2.2 Metadata og release-indhold
+
+`[METADATA]` indeholder coordinate-delene og en obligatorisk single-quoted `DESCRIPTION`. Den valgfrie
+`INFORMATION_URI` er også single-quoted, skal være en syntaktisk gyldig absolut `URI`, og kan bruge enhver scheme,
+for eksempel `https:`, `ftp:` eller `ipfs:`. Nenjim åbner eller fortolker ikke URI'en automatisk.
+
+Hver `[RELEASE major.minor.patch]` indeholder sin egen single-quoted `LICENSE`, `PUBLISHED_AT`, `CONTENT_SIZE` og
+mindst én `CONTENT_DIGEST`. Format 1 accepterer valideret `sha256` og CIDv1 (`cid1`). Licensen er fri tekst, gemmes
+uden normalisering og kan være forskellig mellem releases; fremtidig licensfiltrering er ikke implementeret.
+
+### 2.3 Komplette snapshots og Journal-kæden
+
+Hver Journal-fil er et komplet immutable snapshot af al aktuel viden om artifakten og dens kendte releases. En
+revision er aldrig en delta og arver intet implicit. En nyere revision kan ændre metadata, policy, dependencies og
+selv korrigere eller fjerne tidligere kendt release-information. Et no-op snapshot er også gyldigt.
+
+`JOURNAL_VERSION` er et strengt stigende UTC-timestamp med millisekundpræcision:
+
+```text
+uuuuMMddHHmmssSSS'Z'
+```
+
+Genesis-revisionen udelader `PREVIOUS_JOURNAL_DIGEST`. Hver efterfølger refererer til SHA-256 over forgængerens
+komplette UTF-8-tekst præcis som leveret, inklusive whitespace og linjeskift. Manglende forgængere, forks, flere
+genesis-revisioner, fremmede artifaktkæder og ikke-stigende versioner afvises.
+
+`PUBLISHED_AT` er release-tid og er uafhængig af Journalens publiceringstid. Historiske queries vælger et helt
+snapshot ud fra Journal-kæden; de filtrerer ikke det nyeste snapshot efter `PUBLISHED_AT`.
+
+### 2.4 Version expressions
+
+En `SemanticVersion` (`1.0.3`) er én eksakt release. En `VersionExpression` beskriver et sæt acceptable releases:
+
+* `1.0.3` og `[1.0.3]` er samme eksakte selector.
+* `[1.0]` betyder hele den stabile `1.0.x`-serie, ikke eksakt `1.0.0`.
+* `[1.0.3-->1.0.7]` inkluderer begge grænser; `)` ekskluderer øvre grænse.
+* `[1.0-->1.2]` inkluderer hele `1.2.x`; `[1.0-->1.2)` gør ikke.
+* `[1.0-->` stopper før `2.0.0`; `(1.0-->` starter ved `1.1.0`.
+* Komma adskiller en union af expressions.
+
+Endpoints skal mindst indeholde major og minor. Matematiske operatorer som `>=`, prereleases, build-metadata,
+tomme elementer, omvendte ranges og implicitte cross-major open ranges afvises.
+
+### 2.5 Dependencies
+
+Dependencies hører til en bestemt artifaktrelease og bruger altid en explicit scheme. Format 1 implementerer kun:
+
+```text
+DEPENDS_ON=nenjim:com_r35157_nenjim-hubd-api=[1.0-->
+EXCLUDES=nenjim:com_r35157_nenjim-hubd-api=1.0.5:'Known incompatibility'
+PREFERRED=nenjim:com_r35157_nenjim-hubd-api=1.0.3:'Built together'
+```
+
+`DEPENDS_ON` er basissættet. `EXCLUDES` er en hård relationel begrænsning. `PREFERRED` er kun et hint og skal være
+en delmængde af `DEPENDS_ON - EXCLUDES`. Flere exclusion/preference-linjer for samme target kombineres som union,
+men deres individuelle beskrivelser bevares. Ukendte schemes, herunder `maven:`, afvises i format 1.
+
+### 2.6 Artifact policy
+
+Den valgfrie `[POLICY]` bevarer individuelle regler og beskrivelser:
+
+* `BLACKLIST` er en hård global regel: matchende releases må ikke vælges.
+* `DISCOURAGED` er et negativt hint: releasen kan stadig vælges.
+* `RECOMMENDED` er et positivt hint til én eksakt release, som findes i samme snapshot.
+
+Overlap er tilladt, og hårde regler vinder over hints. En fremtidig resolver bør søge en gyldig graf med flest muligt
+kompatible anbefalinger; højeste versionsnummer er fallback, ikke en ubetinget regel. Det kan senere føre til
+konvergens fra en højere lokal release til en lavere anbefalet release, men den adfærd er ikke implementeret nu.
+
+### 2.7 Parser og immutable model
+
+Parseren kræver `FORMAT_VERSION=1` som første faktiske entry, men tillader blanke linjer og `#`-kommentarer.
+`#` inde i single quotes er tekst. Quoted værdier understøtter `\'` og `\\`. Ukendte, malformed, duplikerede eller
+forkert placerede felter/sektioner afvises med source, linjenummer og årsag. Hele dokumentet valideres før servicens
+state ændres. Alle publicerede modeller og collections er immutable og defensivt kopieret.
+
+### 2.8 JournalService, JournalServiceManager og disk-layout
+
+En `Service` er det domæne-API, som applikationer og andre services bruger i daglig drift. `JournalService` er derfor
+filesystem-uafhængigt og read-only: det kan vise coordinates, kronologiske revisionslister, latest, exact og
+newest-at-or-before snapshots samt en eksakt release fra et valgt snapshot. Det eksponerer ikke start/stop,
+filesystem paths, refresh, parser eller mutation.
+
+En `ServiceManager` ejes af en composition/lifecycle owner og håndterer start, stop, configuration/data location,
+refresh og adgang til den tilhørende Service. `JournalServiceManager` ejer den normaliserede Journal-root. Ved start
+læser referenceimplementationen komplette UTF-8-filer kronologisk, validerer placement/navne og gør først sit
+`JournalService` tilgængeligt, når hele initial loading er lykkedes. Refresh er explicit og idempotent; der er ingen
+watcher eller background polling, og stop ændrer ikke Journal-filer.
+
+`JournalServiceImpl` vedligeholder internt kæderne og udfører atomisk ingestion med exact-text SHA-256. Identisk tekst
+er idempotent; anderledes tekst med samme coordinate og Journal-version er en conflict. Parser, ingestion og mutable
+chain state er implementation details og findes ikke i public signatures. Public API-pakkerne er opdelt således:
+
+```text
+com.r35157.nenjim.service.journal               JournalService, JournalServiceManager
+com.r35157.nenjim.service.journal.model         sammensatte immutable domænemodeller
+com.r35157.nenjim.service.journal.valuetypes    små værdidefinerede typer
+com.r35157.nenjim.service.journal.exception     Journal-specifikke exceptions
+com.r35157.nenjim.service.journal.impl.ref      referenceimplementation og interne helpers
+```
+
+```text
+data/nenjim/journals/
+└── <artifact-coordinate>/
+    ├── <journal-version>.journal
+    └── <journal-version>.journal.example
+```
+
+Kun `.journal` er runtime-input. `.journal.example` dokumenterer formatet og indlæses ikke. Roden skal allerede
+eksistere og være læsbar; service-manageren opretter, overskriver eller sletter ikke Journal-filer.
 
 ## 3. Opdateringer og Sikkerhed
-Nenjim holder automatisk øje med opdateringer gennem det der kaldes journaler. Hvis der opdages en sikkerhedsbrist
-i en bestemt version, opdaterer udviklerne journalen, og alle NenjimHubs vil automatisk hente den nye sikrede version,
-eller nedgradere til en tidligere version indtil en opdatering er klar. På denne måde spredes opdateringer hurtigt
-og effektivt i hele netværket.
+Det implementerede Journal-lag kan repræsentere nye sikkerhedsoplysninger som en nyere immutable revision, for
+eksempel via `BLACKLIST` eller en ændret `RECOMMENDED`. Automatisk synchronization, selection, reconciliation og
+upgrade/downgrade er fremtidigt arbejde.
 
 ## 4. Betalingssystem og Integration med AssetAZ
-For at understøtte betaling for softwarepakker har Nenjim en integration med AssetAZ. Det betyder, at udviklere kan
-vælge at modtage betaling for deres pakker enten som engangsbeløb, abonnement eller per brug. Det hele håndteres
-via kryptovaluta.
+Betaling og AssetAZ-integration er langsigtet vision og er ikke en del af Journal-formatet eller denne implementation.
 
 ## 5. Backing Store og Fleksibilitet
-Nenjim giver fuld fleksibilitet i forhold til, hvor data lagres. Det kan være via på IPFS, i en lokal mappe, eller
-endda i en database. Systemet er designet til at være så fleksibelt, at udviklere kan vælge den løsning, der
-passer bedst til deres behov.
+Den nuværende `JournalServiceManagerImpl` læser kun det dokumenterede lokale disk-layout. Artifact downloading, IPFS retrieval,
+remote Journals og andre backing stores er ikke implementeret. En `ipfs:`-værdi i `INFORMATION_URI` er metadata,
+ikke en retrieval-instruks.
 
 ## 6. Standardiseret og Automatiseret Pakkehåndtering
-En af de store fordele ved Nenjim er, at brugere ikke længere behøver at søge manuelt efter afhængigheder på
-Internettet. Nenjim benytter en standardiseret metode til at finde og downloade pakker automatisk f.eks. via IPFS.
-Det betyder, at alle pakker er let tilgængelige og kan hentes på en ensartet måde, hvilket sparer tid og sikrer
-en mere strømlinet oplevelse for både udviklere og brugere.
+Journalen modellerer dependency-krav og indholdsidentiteter, men downloader ikke bytes og verificerer ikke downloadet
+indhold. Dependency-graph resolution, automatisk release-selection og Maven-resolution er fremtidigt arbejde.
 
 ## 7. Betydningen af Semantisk Versionering
-For at Nenjim kan fungere optimalt, er det essentielt, at alle pakker følger principperne for semantisk
-versionering. Det betyder, at hver version af en pakke tydeligt angiver, om der er tale om en mindre opdatering,
-en fejlrettelse eller en større, potentielt inkompatibel ændring. Ved at overholde disse versioneringsregler
-kan Nenjim nemt og sikkert håndtere opdateringer og sikre, at systemet altid er stabilt og velfungerende.
+Format 1 accepterer kun stabile eksakte releases med alle tre numeriske komponenter. Det forudsætter ikke, at en
+resolver altid vælger den numerisk højeste version: hard constraints afgrænser de gyldige valg, og policy/dependency
+hints kan på sigt foretrække en lavere kompatibel release.
 
 ## 8. Integration af Plugins og Centralt Registry
-En af de unikke fordele ved at benytte Nenjim er, at applikationer kan kommunikere direkte med NenjimHub'en
-for at finde og integrere nye plugins. Gennem et globalt registry kan applikationer søge efter plugins,
-der implementerer bestemte interfaces af specifikke versioner, og dermed let udvide deres funktionalitet.
-Denne fleksibilitet gør det muligt for brugere at tilføje nye features eller forbedringer, som for eksempel
-codecs til en videoafspiller og samtidig se, hvad de forskellige plugins koster.
+Plugin discovery, et centralt registry, Journal publishing, remote synchronization og signature-validering er
+fremtidig vision. De er ikke implementeret af Journal-modellen, servicen eller service-manageren.
 
 ## 9. Integration med AssetAZ og økonomisk aktivitet
-Nenjim er designet til at være et åbent og frit værktøj til håndtering af afhængigheder, versionering og afvikling af
-softwarepakker. Systemet kan bruges uden nogen form for betaling, og alle grundlæggende funktioner – som f.eks.
-lokal injektion, analyse af afhængigheder og dynamisk classloading – er tilgængelige uden krav om økonomisk interaktion.
-Men i de tilfælde, hvor brugeren ønsker at gøre sin software offentligt tilgængelig for andre – f.eks. ved at
-propagere pakker til et registry eller sælge sin software – vil der være knyttet en lille økonomisk omkostning til
-disse handlinger.
-For at understøtte denne form for aktivitet, anvender Nenjim den digitale AssetAZ crypto token. Denne token er
-en del af den bredere AssetAZ-platform og giver mulighed for mikrobetalinger i forbindelse med softwaredistribution.
-Ved at benytte en dedikeret token opnås en decentral og gennemsigtig afregningsmekanisme, samtidig med at det skaber
-en naturlig kobling til AssetAZ, hvor hele den økonomiske infrastruktur er forankret.
-Det er vigtigt at bemærke, at denne integration ikke begrænser brugen af Nenjim i almindelige, ikke-kommercielle
-sammenhænge, men i det øjeblik man ønsker at publicere og distribuere software med økonomisk formål – og dermed
-også deltage i registrering og transaktionslogik – kræver det at AssetAZ og dens token anvendes.
-På den måde skabes et bæredygtigt økosystem, hvor det er gratis at bruge og eksperimentere, men koster et lille beløb
-at gøre noget kommercielt.
+Økonomi, publicering og distribution er fremtidig vision. Format 1 beskriver alene artifaktviden; det indeholder
+ingen betalings-, salgs- eller transaktionsadfærd.
 
 ## 10. Installation af en NenjimHub
 For at NenjimHub'en kan køre godt, skal den leve i et samspil med nogle andre komponenter. Dette kan sættes op på