com_r35157_nenjim-hubd-impl_ref/openspec/changes/archive/2026-08-20-75-implement-nenjim-journal/proposal.md

Why

Nenjim needs a stable, executable Journal foundation before Context and classloader work can continue. The Journal API must also follow Nenjim's service architecture so ordinary consumers receive a filesystem-independent read-only service while lifecycle and data-source administration remain with a separate service manager.

What Changes

• Add an immutable public Journal domain model for one artifact per Journal, exact releases, content identity, dependencies, policy, and normalized version expressions.
• Add strict format-version-1 parsing and whole-document validation, including quoted metadata/license text, timestamps, digests, dependency constraints, policy, and precise source/line diagnostics.
• Add a filesystem-independent, read-only JournalService query interface and a reference JournalServiceImpl that maintains independent immutable revision chains behind an internal ingestion operation.
• Add a lifecycle and administrative JournalServiceManager interface and filesystem-facing JournalServiceManagerImpl that owns the data root, performs initial chronological loading and explicit refresh, and exposes the service only after successful start.
• Separate the two central service interfaces, composed models, value types, exceptions, and reference implementation into the mandated public and implementation packages.
• BREAKING: Remove the intermediate com.r35157.nenjim.journal API, its public JournalManager, and the older hubd.journal, hubd.module, JournalManagerImpl, and JournalId skeletons without compatibility aliases.
• Move the three example Journals into artifact-coordinate revision directories and rewrite them as valid format-version-1 snapshots.
• Rewrite Nenjim documentation and terminology around artifact-scoped immutable snapshots, chain history, dependency/policy semantics, content/license metadata, and the general Service/ServiceManager responsibility split.
• Keep Contexts, resolution, release selection, classloading, retrieval, signatures, publishing, synchronization, watching, UI/CLI, URI interpretation, and license filtering outside this change.

Capabilities

New Capabilities

• nenjim-journal-format: Defines the immutable Journal model, format-version-1 grammar, version-expression semantics, and complete structural and semantic validation contract.
• nenjim-journal-management: Defines the read-only query service, lifecycle manager, internal atomic Journal-chain ingestion, package boundary, and filesystem refresh/layout behavior.

Modified Capabilities

None.

Impact

• The only types directly under com.r35157.nenjim.service.journal are JournalService and JournalServiceManager; public models, value types, and exceptions use their specified subpackages.
• Reference parsing, mutable ingestion, chain state, and filesystem loading live under com.r35157.nenjim.service.journal.impl.ref and do not leak through public signatures.
• Existing obsolete Journal/module source files and references are removed or rewritten.
• Journal examples under data/nenjim/journals and docs/Nenjim.md, docs/Terminologi.md, and docs/Nenjim-public.html change substantially.
• No new external dependency or runtime integration with Context/classloading is introduced.