127 lines
8.9 KiB
HTML
127 lines
8.9 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="UTF-8">
|
|
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|
<title>Nenjim Journal Documentation</title>
|
|
<style>
|
|
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>
|
|
<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>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><GROUP>-<MODULE>-<ARTIFACT>
|
|
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>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>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>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-->1.0.7]</code></td><td>A closed range including both exact endpoints.</td></tr>
|
|
<tr><td><code>[1.0-->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--></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>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-->
|
|
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>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>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>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/
|
|
└── <artifact-coordinate>/
|
|
├── <journal-version>.journal
|
|
└── <journal-version>.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>
|
|
|
|
<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>
|