com_r35157_nenjim-hubd-impl_ref/docs/Nenjim-public.html

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>Nenjim 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</h1>
    <p class="status"><strong>Implementation status:</strong> Journal format version 1, the immutable Java model,
        internal strict parser, read-only <code>JournalService</code> with a Hub-managed process implementation,
        passive explicitly refreshed <code>JournalServiceManager</code>, Hub-managed
        <code>JavaFxRuntimeService</code>, and the first central component Registry are implemented. Contexts,
        resolution, classloading, discovery, runtime loading/removal, downloading, publishing, synchronization,
        watching, signatures, permissions, 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>&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>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--&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>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>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, process, 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 a registrable component but remains filesystem-independent and
        read-only: it exposes current and historical Journal queries without lifecycle, paths, refresh, parser, or
        mutation operations. Queries become available only after successful Journal process startup.</p>
    <p>The Hub constructs one Journal object exposed as both <code>JournalService</code> and
        <code>NenjimProcess</code>, plus one distinct passive <code>JournalServiceManager</code>. The manager reports
        the normalized data root and performs explicit refresh; it has no start, stop, service accessor, component
        identity, or process lifecycle. It delegates through a package-private administration view that ordinary
        service consumers cannot name or derive.</p>
    <p>The Journal process reads UTF-8 runtime files chronologically and validates directory and filename placement.
        Its complete initial worldview is published only after every runtime file succeeds; failed startup leaves
        queries unavailable and cannot be retried on the same instance. Later refresh remains explicit, idempotent,
        and atomic per ingestion. Neither startup nor refresh creates, overwrites, or deletes Journal files.</p>
    <p>The package-private <code>JournalServiceImpl</code> keeps exact-text SHA-256 identity, chain state,
        idempotency, conflicts, forks, and 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, filesystem
        loading, and the admin boundary live under <code>.impl.ref</code> without leaking through public
        signatures.</p>
    <p>All modern JavaFX applications share one JVM-wide toolkit. The Hub constructs one
        <code>JavaFxRuntimeServiceImpl</code>, registers it as <code>nenjim.javafx-runtime.service</code>, starts it
        through its <code>NenjimProcess</code> view, and injects its lifecycle-free service view into active Mission
        Control and Process Manager. All six modern JavaFX implementations require that service in their constructor.
        Only service startup calls <code>Platform.startup(...)</code>; task submission never initializes or retries
        JavaFX and is rejected until startup succeeds. Startup waits until the JavaFX Application Thread is ready and
        sets <code>Platform.setImplicitExit(false)</code>, keeping the shared runtime alive after the last window
        closes.</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>

    <h2>Components and the central Registry</h2>
    <p>A Nenjim component is a fully constructed building block ready for use. Its consumer decides whether it acts
        as a service, application, algorithm, or adapter. A service exposes a domain API, while application describes
        a user-facing or orchestration role. <code>NenjimComponent</code> is therefore a pure marker. Independently,
        the canonical <code>com.r35157.nenjim.process.NenjimProcess</code> marks an active component that the Hub can
        start and track; it adds only <code>start()</code> and no common stop, restart, or health operation.</p>
    <p>A <code>NenjimComponentId</code> is lower-case lookup metadata owned by one Registry, not a property of the
        object, an authorization boundary, or an artifact version. One object may have several IDs. Conversely, one
        registration is indexed under every component interface implemented by that object, so the Registry object's
        typed service and process views retain reference identity.</p>
    <p><code>NenjimRegistryService</code> is the injected read-only consumer view. It returns immutable,
        registration-ordered ID snapshots for a component interface and supports lookup by explicit ID plus expected
        interface. Missing IDs return <code>null</code>; requesting an existing ID through the wrong interface is a
        caller error. Registration is available only through a package-private administration view behind the passive
        Registry manager. That manager exposes only registration, is neither a component nor a process, is not
        registered, and cannot start anything. The internal administration interface must remain package-private so
        an ordinary service consumer cannot cast the Registry object to a mutation view.</p>
    <p><code>NenjimHubImpl</code> is the global composition and runtime owner. It constructs the Registry assembly,
        starts and registers Registry first, and records its successful process ID. It then constructs the Journal
        assembly for <code>data/nenjim/journals</code>, registers <code>nenjim.journal.service</code>, starts Journal
        second, and records it only after complete successful loading. Only then does the Hub construct the hardcoded
        business component graph in dependency order. A Journal failure therefore stops startup before Ticker,
        Evelyn, Burner, the JavaFX runtime, Mission Control, Process Manager, the online point, and the blocking
        wait.</p>
    <p>The Ticker explicitly selects the Raydium EVE/USDT source ID while the hardcoded source remains registered but
        inactive. After Registry and Journal, the Hub activates the explicit Ticker, Production Evelyn, Test Evelyn,
        Production IOU Burner, JavaFX runtime service, Mission Control, and Process Manager sequence; it does not
        start every registered process. The shared JavaFX runtime is therefore active before either enabled JavaFX
        application. Successful process IDs, including <code>nenjim.javafx-runtime.service</code>, are exposed as
        immutable ordered point-in-time snapshots without implying continued health. A JavaFX startup failure is
        fail-fast and prevents Mission Control and Process Manager from starting.</p>
    <p><code>com.r35157.nenjim.hubd.Main</code> remains only the outer Java bootstrap. It constructs the reference Hub
        through the public <code>NenjimHub</code> interface and calls <code>start()</code> once. The Hub is neither a
        component nor a process and is not registered inside its own Registry.</p>
    <p>The Registry remains internally open to later registration, but this version has one catalogue and no Context,
        version resolution, classloader integration, discovery, public runtime loading or registration, removal,
        persistence, events, ownership tracking, usage counts, permissions, scopes, filtered views, or automatic
        selection.</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>