# Nenjim Journal Documentation

# Nenjim Journals

Implementation status: Journal format version 1, the immutable Java model, internal strict parser, read-only `JournalService`, and explicitly refreshed lifecycle `JournalServiceManager` are implemented. Contexts, resolution, classloading, downloading, publishing, synchronization, watching, signatures, 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.

## 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.