# Nenjim

Implementation status: Journal format version 1, the immutable Java model, internal strict parser, read-only `JournalService`, explicitly refreshed lifecycle `JournalServiceManager`, 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.

## One Journal per artifact

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 `TYPE`.

    <GROUP>-<MODULE>-<ARTIFACT>
    com_r35157_nenjim-hubd-api
    com_r35157_nenjim-hubd-api:1.0.3

The three metadata components identify the chain; there is no separate `JOURNAL_ID`.

## Complete immutable snapshots and history

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.

The genesis omits `PREVIOUS_JOURNAL_DIGEST`. 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.

`JOURNAL_VERSION` is when the worldview was published. `PUBLISHED_AT` is when an artifact release was published. Both use `uuuuMMddHHmmssSSS'Z'`, but historical knowledge is selected from the Journal chain rather than by filtering the newest snapshot on release publication time.

## Metadata and release content

`DESCRIPTION` is mandatory single-quoted text. `INFORMATION_URI` 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.

Every exact `major.minor.patch` release has a mandatory single-quoted `LICENSE`, a publication timestamp, non-negative byte size, and one or both supported content identities: `sha256` and CIDv1 (`cid1`). License text is preserved as free text; no vocabulary, compatibility decision, or filtering is applied.

## Version expressions

Expression | Meaning
--- | ---
`1.0.3`, `[1.0.3]` | The same exact release.
`[1.0]` | Every stable 1.0.x release; not exact 1.0.0.
`[1.0.3-->1.0.7]` | A closed range including both exact endpoints.
`[1.0-->1.2)` | Includes 1.0.x and 1.1.x, excluding the complete 1.2.x series.
`[1.0-->` | Starts at 1.0.0 and stops before 2.0.0.

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.

## Dependencies

Dependencies belong to individual releases and always have an explicit scheme. Format 1 implements only the `nenjim:` scheme; Maven resolution and unknown schemes are not silently accepted.

    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` is the hard base set. `EXCLUDES` removes hard-invalid combinations for that relationship. `PREFERRED` is a hint and must remain a subset of `DEPENDS_ON - EXCLUDES`. Repeated rules form unions while each line and description remains inspectable. The Journal layer represents these rules but does not resolve a graph.

## Artifact policy

- `BLACKLIST` is a hard global prohibition.
- `DISCOURAGED` is a negative hint; a matching release remains selectable.
- `RECOMMENDED` is a positive hint naming one exact release in the same snapshot.

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.

## Strict parsing and immutable model

`FORMAT_VERSION=1` must be the first actual entry. Blank lines and comments beginning with `#` are accepted, while a hash inside single quotes is data. Quoted values support escaped quotes (`\'`) and backslashes (`\\`). 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.

## Service, ServiceManager, packages, and disk layout

A `Service` is the public domain API used by applications and other services during ordinary operation. `JournalService` is therefore filesystem-independent and read-only: it exposes current and historical Journal queries without lifecycle, paths, refresh, parser, or mutation operations.

A `ServiceManager` is the lifecycle and administrative API owned by a composition/lifecycle owner. `JournalServiceManager` starts and stops the Journal service, reports its normalized data root, performs explicit refresh, and exposes `JournalService` 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.

`JournalServiceImpl` 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 `.model`, `.valuetypes`, and `.exception`, while parser, ingestion, chain state, and filesystem loading live under `.impl.ref` without leaking through public signatures.

    data/nenjim/journals/
    └── <artifact-coordinate>/
        ├── <journal-version>.journal
        └── <journal-version>.journal.example

Only `.journal` files are runtime input. Version-controlled `.journal.example` files are documentation and are ignored by the service.

## Components and the central Registry

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. `NenjimComponent` is therefore a pure marker, while `NenjimApplication` adds only a common `start()` operation and no common stop.

A `NenjimComponentId` 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 its typed service and application views retain reference identity.

`NenjimRegistryService` 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 `null`; requesting an existing ID through the wrong interface is a caller error. Registration is available only through a package-private administration view retained by the Registry manager.

`NenjimRegistryServiceManagerImpl` starts and registers the Registry first, registers itself second, and then constructs and registers the hardcoded component graph in dependency order. Applications own their selection and activation: the Ticker explicitly selects the Raydium EVE/USDT source ID while the hardcoded source remains registered but inactive. The manager activates only the existing explicit five-application sequence; it does not start every `NenjimApplication`. `com.r35157.nenjim.hubd.Main` is only the outer Java bootstrap; `Main.main(...)` starts this manager and is not itself a component or application.

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.

## Future Nenjim vision

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.