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>