r35157/com_r35157_nenjim-hubd-impl_ref
0
0
Fork 0
Code Issues 8 Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
minimons
2026-08-20 12:28:16 +02:00
parent f29013e9c2
commit b230e15ece
43 changed files with 3303 additions and 276 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/Nenjim-public.html
+107 -110
View File
@@ -2,128 +2,125 @@
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Nenjim Documentation</title>
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Nenjim Journal Documentation</title>
<style>
body {
font-family: Arial, sans-serif;
background-color: #f8f9fa;
color: #333;
margin: 0;
padding: 0;
}
.container {
width: 80%;
max-width: 1000px;
margin: auto;
padding: 20px;
background-color: #fff;
}
h1, h2 {
color: #0056b3;
}
.toc {
background: #e7f1ff;
padding: 10px 20px;
border-left: 4px solid #0056b3;
margin-bottom: 30px;
}
.footer {
text-align: center;
padding: 20px;
border-top: 1px solid #ddd;
margin-top: 40px;
color: #777;
}
body { font-family: Arial, sans-serif; background: #f8f9fa; color: #263238; margin: 0; }
main { max-width: 980px; margin: auto; padding: 2rem; background: white; line-height: 1.55; }
h1, h2, h3 { color: #0056b3; }
code, pre { background: #f1f3f5; }
code { padding: .1rem .25rem; }
pre { padding: 1rem; overflow-x: auto; border-left: 4px solid #0056b3; }
.status { padding: 1rem; background: #e7f1ff; border-left: 4px solid #0056b3; }
table { border-collapse: collapse; width: 100%; }
th, td { border: 1px solid #ccd4da; padding: .55rem; text-align: left; vertical-align: top; }
</style>
</head>
<body>
<div class="container">
<h1>Nenjim Documentation</h1>
<div class="toc">
<h2>Table of Contents</h2>
<ul>
<li><a href="#1-introduction-to-nenjim">1. Introduction to Nenjim</a></li>
<li><a href="#2-versioning-and-dependencies">2. Versioning and Dependencies</a></li>
<li><a href="#3-updates-and-security">3. Updates and Security</a></li>
<li><a href="#4-payment-system-and-integration-with-assetaz">4. Payment System and Integration with AssetAZ</a></li>
<li><a href="#5-backing-store-and-flexibility">5. Backing Store and Flexibility</a></li>
<li><a href="#6-standardized-and-automated-package-management">6. Standardized and Automated Package Management</a></li>
<li><a href="#7-importance-of-semantic-versioning">7. Importance of Semantic Versioning</a></li>
<li><a href="#8-integration-of-plugins-and-central-registry">8. Integration of Plugins and Central Registry</a></li>
<li><a href="#9-integration-with-assetaz-and-economic-activity">9. Integration with AssetAZ and Economic Activity</a></li>
</ul>
</div>
<h1>Nenjim Documentation</h1>
<h2 id="1-introduction-to-nenjim">1. Introduction to Nenjim</h2>
<p>Nenjim is an innovative system that enables handling multiple versions of software packages simultaneously.</p>
<p>The system solves the challenge of dependencies and versioning by using unique version numbers in the naming of
packages,</p>
<p>which ensures that multiple versions of the same software package can exist side by side without conflicts.</p>
<main>
<h1>Nenjim Journals</h1>
<p class="status"><strong>Implementation status:</strong> Journal format version 1, the immutable Java model,
internal strict parser, read-only <code>JournalService</code>, and explicitly refreshed lifecycle
<code>JournalServiceManager</code> are implemented. Contexts, resolution, classloading, downloading, publishing,
synchronization, watching, signatures, and license filtering remain future work.</p>
<h2 id="2-versioning-and-dependencies">2. Versioning and Dependencies</h2>
<p>Nenjim uses a method where packages are named with the version number directly in the package name. However,
this is managed in so-called journals outside of the actual code, so that the Java code itself does not depend
on Nenjim.</p>
<p>This ensures that developers do not have to worry about version conflicts, as each dependency refers precisely
to the version it needs. The system ensures that all necessary modules are available and kept up to date in
the background.</p>
<h2>One Journal per artifact</h2>
<p>A Journal describes exactly one artifact. API, test, and implementation artifacts therefore have independent
Journals and chains. Roles such as API or implementation are not stored as a <code>TYPE</code>.</p>
<pre><code>&lt;GROUP&gt;-&lt;MODULE&gt;-&lt;ARTIFACT&gt;
com_r35157_nenjim-hubd-api
com_r35157_nenjim-hubd-api:1.0.3</code></pre>
<p>The three metadata components identify the chain; there is no separate <code>JOURNAL_ID</code>.</p>
<h2 id="3-updates-and-security">3. Updates and Security</h2>
<p>Nenjim automatically monitors for updates through what are called journals. If a security vulnerability is
discovered in a particular version, the developers update the journal, and all NenjimHubs will automatically
fetch the new secure version, or downgrade to a previous version until an update is ready. In this way,
updates are distributed quickly and efficiently throughout the entire network.</p>
<h2>Complete immutable snapshots and history</h2>
<p>Every Journal revision is a complete worldview of the artifact and all releases known in that revision. It is
not a delta and inherits nothing implicitly. A later snapshot may change metadata, add or remove releases,
correct release knowledge, alter dependencies or policy, or be a semantic no-op.</p>
<p>The genesis omits <code>PREVIOUS_JOURNAL_DIGEST</code>. Each successor names the SHA-256 digest of the
predecessor's exact UTF-8 text, including whitespace and line endings. A chain has one genesis and one head;
missing predecessors, forks, cross-artifact links, and non-increasing Journal versions are invalid.</p>
<p><code>JOURNAL_VERSION</code> is when the worldview was published. <code>PUBLISHED_AT</code> is when an artifact
release was published. Both use <code>uuuuMMddHHmmssSSS'Z'</code>, but historical knowledge is selected from
the Journal chain rather than by filtering the newest snapshot on release publication time.</p>
<h2 id="4-payment-system-and-integration-with-assetaz">4. Payment System and Integration with AssetAZ</h2>
<p>To support payment for software packages, Nenjim integrates with AssetAZ. This means that developers can choose
to receive payment for their packages either as a one-time fee, as a subscription, or per use. All transactions
are handled via cryptocurrency.</p>
<h2>Metadata and release content</h2>
<p><code>DESCRIPTION</code> is mandatory single-quoted text. <code>INFORMATION_URI</code> is optional single-quoted
metadata and must decode to a non-empty absolute URI. Format 1 does not restrict schemes: HTTPS, FTP, IPFS,
and other syntactically valid schemes are accepted without opening or interpreting their content.</p>
<p>Every exact <code>major.minor.patch</code> release has a mandatory single-quoted <code>LICENSE</code>, a
publication timestamp, non-negative byte size, and one or both supported content identities:
<code>sha256</code> and CIDv1 (<code>cid1</code>). License text is preserved as free text; no vocabulary,
compatibility decision, or filtering is applied.</p>
<h2 id="5-backing-store-and-flexibility">5. Backing Store and Flexibility</h2>
<p>Nenjim provides complete flexibility regarding where data is stored. This can be via IPFS, in a local folder,
or even in a database. The system is designed to be so flexible that developers can choose the solution that
best fits their needs.</p>
<h2>Version expressions</h2>
<table>
<thead><tr><th>Expression</th><th>Meaning</th></tr></thead>
<tbody>
<tr><td><code>1.0.3</code>, <code>[1.0.3]</code></td><td>The same exact release.</td></tr>
<tr><td><code>[1.0]</code></td><td>Every stable 1.0.x release; not exact 1.0.0.</td></tr>
<tr><td><code>[1.0.3--&gt;1.0.7]</code></td><td>A closed range including both exact endpoints.</td></tr>
<tr><td><code>[1.0--&gt;1.2)</code></td><td>Includes 1.0.x and 1.1.x, excluding the complete 1.2.x series.</td></tr>
<tr><td><code>[1.0--&gt;</code></td><td>Starts at 1.0.0 and stops before 2.0.0.</td></tr>
</tbody>
</table>
<p>Comma-separated expressions form a union. Boundaries require at least major and minor. Mathematical
comparison syntax, incomplete bare exact versions, prereleases, build metadata, empty elements, and reversed
or empty ranges are rejected.</p>
<h2 id="6-standardized-and-automated-package-management">6. Standardized and Automated Package Management</h2>
<p>One of the major advantages of Nenjim is that users no longer have to manually search for dependencies on the
Internet. Nenjim uses a standardized method to automatically find and download packages, for example via IPFS.
This means that all packages are easily accessible and can be retrieved in a consistent manner, which saves
time and ensures a more streamlined experience for both developers and users.</p>
<h2>Dependencies</h2>
<p>Dependencies belong to individual releases and always have an explicit scheme. Format 1 implements only the
<code>nenjim:</code> scheme; Maven resolution and unknown schemes are not silently accepted.</p>
<pre><code>DEPENDS_ON=nenjim:com_r35157_nenjim-hubd-api=[1.0--&gt;
EXCLUDES=nenjim:com_r35157_nenjim-hubd-api=1.0.5:'Known incompatibility'
PREFERRED=nenjim:com_r35157_nenjim-hubd-api=1.0.3:'Built together'</code></pre>
<p><code>DEPENDS_ON</code> is the hard base set. <code>EXCLUDES</code> removes hard-invalid combinations for that
relationship. <code>PREFERRED</code> is a hint and must remain a subset of
<code>DEPENDS_ON - EXCLUDES</code>. Repeated rules form unions while each line and description remains
inspectable. The Journal layer represents these rules but does not resolve a graph.</p>
<h2 id="7-importance-of-semantic-versioning">7. Importance of Semantic Versioning</h2>
<p>For Nenjim to function optimally, it is essential that all packages follow the principles of semantic versioning.
This means that each version of a package clearly indicates whether it is a minor update, a bug fix, or a major,
potentially incompatible change. By adhering to these versioning rules, Nenjim can easily and safely handle
updates and ensure that the system is always stable and fully functional.</p>
<h2>Artifact policy</h2>
<ul>
<li><code>BLACKLIST</code> is a hard global prohibition.</li>
<li><code>DISCOURAGED</code> is a negative hint; a matching release remains selectable.</li>
<li><code>RECOMMENDED</code> is a positive hint naming one exact release in the same snapshot.</li>
</ul>
<p>Overlaps are valid and hard rules win over hints. A future resolver should seek a valid graph containing as
many compatible recommendations as possible. The highest valid version is a fallback, not an unconditional
rule, so future convergence may move from a higher local version to a lower recommended version.</p>
<h2 id="8-integration-of-plugins-and-central-registry">8. Integration of Plugins and Central Registry</h2>
<p>One of the unique advantages of using Nenjim is that applications can communicate directly with the NenjimHub to
find and integrate new plugins. Through a global registry, applications can search for plugins that implement
specific interfaces of certain versions, making it easy to extend their functionality. This flexibility allows
users to add new features or improvements, such as codecs for a video player, while also being able to see the
cost of different plugins.</p>
<h2>Strict parsing and immutable model</h2>
<p><code>FORMAT_VERSION=1</code> must be the first actual entry. Blank lines and comments beginning with
<code>#</code> are accepted, while a hash inside single quotes is data. Quoted values support escaped quotes
(<code>\'</code>) and backslashes (<code>\\</code>). Unknown, malformed, duplicate, misplaced, empty, or
semantically inconsistent content fails with source name, one-based line number, and a reason. Validation is
complete before service state changes. Returned objects and collections are immutable and defensively copied.</p>
<h2 id="9-integration-with-assetaz-and-economic-activity">9. Integration with AssetAZ and Economic Activity</h2>
<p>Nenjim is designed to be an open and free tool for managing dependencies, versioning, and the execution of
software packages. The system can be used without any form of payment, and all basic features—such as local
injection, dependency analysis, and dynamic classloading—are available without any economic interaction
required.</p>
<p>However, in cases where the user wants to make their software publicly available to others—for example, by
propagating packages to a registry or selling their software—a small economic cost will be associated with
these actions.</p>
<p>To support this kind of activity, Nenjim uses the digital AssetAZ crypto token. This token is part of the
broader AssetAZ platform and enables micropayments in connection with software distribution.</p>
<p>By using a dedicated token, a decentralized and transparent settlement mechanism is achieved, while also
creating a natural connection to AssetAZ, where the entire economic infrastructure is anchored.</p>
<p>It is important to note that this integration does not limit the use of Nenjim in regular, non-commercial
contexts, but as soon as you wish to publish and distribute software for commercial purposes—and thus also
participate in registration and transaction logic—it requires the use of AssetAZ and its token.</p>
<p>In this way, a sustainable ecosystem is created where it is free to use and experiment, but there is a small
cost for commercial activity.</p>
<h2>Service, ServiceManager, packages, and disk layout</h2>
<p>A <code>Service</code> is the public domain API used by applications and other services during ordinary
operation. <code>JournalService</code> is therefore filesystem-independent and read-only: it exposes current
and historical Journal queries without lifecycle, paths, refresh, parser, or mutation operations.</p>
<p>A <code>ServiceManager</code> is the lifecycle and administrative API owned by a composition/lifecycle owner.
<code>JournalServiceManager</code> starts and stops the Journal service, reports its normalized data root,
performs explicit refresh, and exposes <code>JournalService</code> only after complete successful initial
loading. Its reference implementation reads UTF-8 runtime files chronologically and validates directory and
filename placement. It creates, overwrites, and deletes nothing.</p>
<p><code>JournalServiceImpl</code> keeps exact-text SHA-256 identity, chain state, idempotency, conflicts, forks,
and atomic ingestion internal. The public package contains only the two central interfaces; composed models,
value types, and exceptions live under <code>.model</code>, <code>.valuetypes</code>, and
<code>.exception</code>, while parser, ingestion, chain state, and filesystem loading live under
<code>.impl.ref</code> without leaking through public signatures.</p>
<pre><code>data/nenjim/journals/
└── &lt;artifact-coordinate&gt;/
├── &lt;journal-version&gt;.journal
└── &lt;journal-version&gt;.journal.example</code></pre>
<p>Only <code>.journal</code> files are runtime input. Version-controlled <code>.journal.example</code> files are
documentation and are ignored by the service.</p>
<div class="footer">
<p>Translated and rendered from Nenjim.md</p>
</div>
</div>
<h2>Future Nenjim vision</h2>
<p>Contexts, dependency-graph resolution, automatic selection/reconciliation, runtime upgrade or downgrade,
classloaders, artifact downloads, IPFS retrieval, Maven dependencies, signatures, publishing, remote
synchronization, filesystem watching, and UI/CLI management are deliberately outside this implemented
Journal foundation.</p>
</main>
</body>
</html>
docs/Nenjim.md
+155 -46
View File
@@ -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å
docs/Terminologi.md
+41 -17
View File
@@ -1,18 +1,42 @@
# Tekniske termer
| Term | Beskrivelse |
|--------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Modul | Et modul er den mindste logiske enhed i r35157-økosystemet. Hvert modul indeholder ét samlet ansvarsområde. Et modul består af én API-artifakt, nul eller flere Implementations-artifakter, og typisk ét Test-artifakt. Moduler kan bruges som afhængigheder af andre moduler. |
| Artifakt | Et artifakt er et build-resultat genereret for et modul (fx en JAR-fil, Docker-image eller ZIP-pakke). Artifakter er immutable, signeret og versioneres efter Semantic Versioning. Under udvikling publiceres artifakter typisk til et Maven repository; i drift og distribution håndteres de af Nenjim. |
| GroupId | Et artifakt er tilknyttet en gruppe, f.eks 'com.r35157.libs'. I maven er bruges '.' som skilletegn, mens der bruges '_' til repositories. |
| ModuleId | Et artifakt er en del af et modul
| ArtifaktId | Et artifakt id er unikt og består af <moduleId>-<artifaktType>(-<implId>)
| API-artifakt | Et build output som definerer grænseflader og dokumentation for et modul. |
| Implementations-artifakt | Et build output som lave en, evt. blandt flere, implementationer af de grænseflader som er defineret i API-artifaktet. |
| Test-artifakt | Et build output som er en generel test implementation, som kan teste forskellige Implementations-artifakter for at sikre at det overholder de grænseflader og opførsel som er defineret i API-artifaktet. |
# Domæne specifikke termer
| Term | Beskrivelse |
|----------------|-------------------------------------------------------------------------------------------------------|
| Position Value | Dette er den samlede nutidsværdi af in position (nuværende pris × antal) |
| Base Value | Dette er den pris det har kostet at købe positionen (gennemsnits købspris × antal) |
| Margin Value | Dette er den pris man faktisk har skulle betale for at købe en gearet position (base value / gearing) |
> **Dokumentstatus:** Journal-format version 1 og de tilhørende Java-typer, den interne parser, query-service og lifecycle-manager er
> implementeret. Resolver-, Context-, classloader-, retrieval- og publishing-termer beskriver kun fremtidig vision,
> når det er angivet.
| Term | Beskrivelse |
|------|-------------|
| Service | Det offentlige domæne-API, som applikationer og andre services bruger i daglig drift. Det eksponerer almindelige domæneoperationer, men ikke lifecycle, configuration, data-source administration, refresh, parser eller mutation af intern viden. |
| ServiceManager | Det offentlige lifecycle- og administrations-API, som en composition/lifecycle owner bruger til start, stop, configuration/data location, refresh og adgang til den tilhørende Service efter vellykket initialisering. Det er ikke det query-API, som almindelige consumers bruger. |
| Journal | Et immutable, komplet snapshot af al aktuel viden om præcis én artifakt og dens kendte releases. Journalen er aldrig en delta. |
| ArtifactCoordinate | Journal-kædens stabile identitet, udledt som `<GROUP>-<MODULE>-<ARTIFACT>`, f.eks. `com_r35157_nenjim-hubd-api`. Der findes intet separat `JournalId`. |
| JournalVersion | Journal-snapshottets publiceringstid som UTC med millisekundpræcision: `uuuuMMddHHmmssSSS'Z'`. Den er forskellig fra en releases `PUBLISHED_AT`. |
| Journal-kæde | Én genesis og en lineær række immutable snapshots for samme coordinate. Hver efterfølger refererer med SHA-256 til forgængerens eksakte UTF-8-tekst. |
| Historisk worldview | Hele det snapshot, som var nyest på eller før en valgt `JournalVersion`; det beregnes ikke ved at filtrere et nyere snapshot efter release-tid. |
| Artifact release | En eksakt stabil `major.minor.patch`-version af én artifakt med per-release licens, publication time, content digests, content size og dependencies. |
| DESCRIPTION | Obligatorisk single-quoted artifactbeskrivelse i `[METADATA]`; decoded tekst kan ændres i en senere Journal-revision. |
| INFORMATION_URI | Valgfri single-quoted, syntaktisk gyldig absolut URI. Alle schemes er tilladt; indholdet åbnes eller fortolkes ikke automatisk. |
| LICENSE | Obligatorisk single-quoted fri tekst for hver release. Den normaliseres eller juridisk fortolkes ikke; fremtidig filtrering er ikke implementeret. |
| ContentDigest | Valideret indholdsidentitet. Format 1 understøtter `sha256` og CIDv1 (`cid1`), men downloader eller verificerer ikke artifact-bytes. |
| SemanticVersion | Én eksakt stabil artifaktrelease med major, minor og patch. Prerelease/build metadata understøttes ikke i format 1. |
| VersionExpression | Et normaliseret sæt acceptable releases: exact, minor-serie eller inclusive/exclusive/open range. Mathematical comparison syntax understøttes ikke. |
| DependencyTarget | Et explicit scheme og et scheme-specifikt target. Format 1 implementerer kun `nenjim:<artifact-coordinate>`; Maven-resolution er fremtidig. |
| DEPENDS_ON | Den hårde basisramme af acceptable releases for én dependency-relation. |
| EXCLUDES | En hård relationel regel, som fjerner versioner fra én bestemt `DEPENDS_ON`. Individuelle beskrivelser bevares. |
| PREFERRED | Et hint til en delmængde af `DEPENDS_ON - EXCLUDES`; det kan aldrig gøre en ellers ugyldig version gyldig. |
| BLACKLIST | En hård artifact-policy: matchende releases må ikke vælges. |
| DISCOURAGED | Et negativt artifact-policy-hint: matchende releases bør undgås, men er fortsat selectable. |
| RECOMMENDED | Et positivt hint til én eksakt release, der findes i samme snapshot. Højeste version er kun en fremtidig fallback, ikke en ubetinget selection-regel. |
| JournalService | Filesystem-uafhængigt, read-only Service-API for current og historical Journal-queries. Det eksponerer ingen lifecycle-, path-, refresh-, parser- eller mutationsoperationer. |
| JournalServiceManager | Lifecycle- og administrations-API for JournalService. Det ejer den normaliserede data root, udfører komplet initial loading ved start, stopper servicen, udfører explicit refresh og udleverer JournalService efter vellykket initialisering. |
| Journal referenceimplementation | `JournalServiceImpl`, `JournalServiceManagerImpl`, `JournalTextParser`, intern ingestion, chain state og filesystem-loading under `com.r35157.nenjim.service.journal.impl.ref`; implementation details lækker ikke gennem public signatures. |
| Context | Fremtidig beskrivelse af ønskede/resolverede artifactvalg; ikke implementeret af denne Journal-change. |
| Resolver | Fremtidig komponent for dependency graph og release-selection; Journal-laget repræsenterer reglerne, men vælger ikke en graf. |
# Domænespecifikke termer
| Term | Beskrivelse |
|------|-------------|
| Position Value | Den samlede nutidsværdi af en position (nuværende pris × antal). |
| Base Value | Den pris det har kostet at købe positionen (gennemsnitlig købspris × antal). |
| Margin Value | Den pris man faktisk har betalt for en gearet position (base value / gearing). |