com_r35157_nenjim-hubd-impl_ref/openspec/specs/nenjim-journal-management/spec.md

nenjim-journal-management Specification

Purpose

Defines the public Journal query service, its lifecycle manager, internal atomic chain ingestion, historical query behavior, and explicit filesystem loading of immutable Journal revisions.

Requirements

Requirement: Strict Journal API package boundary

The public Journal API SHALL begin at com.r35157.nenjim.service.journal, where the only directly contained Java types SHALL be the public interfaces JournalService and JournalServiceManager. Public composed domain objects SHALL be under .model, public value types SHALL be under .valuetypes, public Journal-specific exceptions SHALL be under .exception, and the reference implementation and its parser, ingestion, chain-state, and filesystem helpers SHALL be under .impl.ref or its subpackages without leaking implementation types through public signatures.

Scenario: Public package contents

• WHEN the compiled Journal API packages are inspected
• THEN only JournalService and JournalServiceManager are directly in com.r35157.nenjim.service.journal, while composed models, value types, and exceptions are in their respective public subpackages

Scenario: Reference implementation boundary

• WHEN the public service and model signatures are inspected
• THEN they expose no parser, mutable ingestion API, filesystem loader, chain store, or reference-implementation type

Scenario: Superseded API removed

• WHEN the source and compiled Journal API are inspected
• THEN no public JournalManager, deprecated alias, forwarding wrapper, or compatibility type remains under com.r35157.nenjim.journal or another superseded package

Requirement: Filesystem-independent read-only Journal service

JournalService SHALL be the ordinary application-facing, filesystem-independent, read-only API. It SHALL list known artifact coordinates and chronological revisions; obtain latest, exact, and newest-at-or-before revisions; obtain an exact artifact release from a selected revision; return immutable results without null; and expose no lifecycle, path, refresh, parser, configuration, or mutation operation.

Scenario: Chronological and latest queries

• WHEN an artifact has several accepted revisions
• THEN the service lists all complete snapshots in ascending Journal-version order and returns the chain head as latest

Scenario: Exact and as-of historical queries

• WHEN a caller requests an exact revision or the newest revision at or before a Journal version
• THEN the service returns the complete worldview from that chain position rather than filtering a newer snapshot by release publication time

Scenario: Release query from selected worldview

• WHEN a caller requests an exact artifact version from a selected revision
• THEN the release, including license, content, dependencies, and policy context in that snapshot, is returned only if that revision knows it

Scenario: Missing query result

• WHEN a coordinate, revision, as-of revision, or artifact release is unknown
• THEN the service returns an empty optional or immutable empty collection rather than null

Scenario: Read-only boundary

• WHEN an ordinary consumer receives JournalService
• THEN the interface provides no start, stop, filesystem root, refresh, parsing, update, ingestion, or other mutation operation

Requirement: Internal atomic text ingestion and chain identity

The reference service implementation SHALL keep mutable ingestion non-public and filesystem-independent. One ingestion SHALL reject null, empty, or blank input; parse and validate the complete text; compute SHA-256 over its exact UTF-8 bytes including whitespace and line endings; validate its chain relationship; and atomically expose the immutable Journal through JournalService. A failed ingestion SHALL leave every previously accepted revision unchanged for that operation.

Scenario: Valid internal ingestion

• WHEN a complete valid genesis Journal is supplied internally
• THEN it becomes immediately queryable through the read-only service under its metadata-derived coordinate

Scenario: Exact text digest

• WHEN a Journal text is accepted
• THEN its revision digest is calculated from exactly the supplied UTF-8 text, including whitespace and line endings

Scenario: Failed ingestion is atomic

• WHEN an ingestion is null, empty, blank, structurally invalid, semantically invalid, or chain-invalid
• THEN the operation fails and every previously accepted chain and revision remains unchanged

Requirement: Linear per-artifact Journal chains

Each artifact coordinate SHALL have exactly one genesis revision and one linear head. A non-genesis revision SHALL reference the current predecessor's exact SHA-256 digest and have a strictly greater Journal version. Missing, cross-artifact, stale-head, duplicate-genesis, or fork relationships SHALL fail.

Scenario: Valid successor

• WHEN a later revision for the same coordinate references the current head's exact text digest and has a strictly greater Journal version
• THEN it becomes the new head while the predecessor remains historically queryable

Scenario: Missing or cross-artifact predecessor

• WHEN a non-genesis revision references an unknown digest or a digest owned by another artifact coordinate
• THEN ingestion fails without changing either chain

Scenario: Fork or stale predecessor

• WHEN a revision references a known non-head predecessor or attempts another genesis for an existing coordinate
• THEN ingestion fails rather than creating multiple heads

Scenario: Non-increasing revision time

• WHEN a successor Journal version is equal to or earlier than its predecessor's version
• THEN ingestion fails

Requirement: Idempotency and conflicts

Supplying the same coordinate, Journal version, and exact complete text more than once SHALL be idempotent. Supplying different text for an existing coordinate and Journal version SHALL fail as a conflict even if the semantic model would be equal.

Scenario: Repeated identical text

• WHEN an already accepted complete text is supplied again
• THEN the existing immutable revision is returned without changing the chain

Scenario: Conflicting text

• WHEN different text is supplied for an already stored coordinate and Journal version
• THEN ingestion reports a conflict and does not mutate state

Requirement: Journal service lifecycle manager

JournalServiceManager SHALL be the lifecycle and administrative API. It SHALL start and stop the service, report the normalized configured Journal data root, perform explicit refresh, and expose the corresponding JournalService only after successful initialization. It SHALL not duplicate the Journal query API.

Scenario: Successful initial start

• WHEN the configured root and all runtime Journal data are valid
• THEN start performs the complete initial chronological load before the manager reports success and exposes its read-only service

Scenario: Failed initial start

• WHEN the root, placement, filename, text, or chain is invalid during initial loading
• THEN start fails clearly and the manager does not report a started service or expose a partially loaded service

Scenario: Service access follows lifecycle

• WHEN service access or refresh is requested before successful start or after stop
• THEN the manager rejects the operation as unavailable in the current lifecycle state

Scenario: Stop is non-destructive

• WHEN the manager is stopped
• THEN service-owned maintenance stops cleanly without creating, rewriting, or deleting Journal files

Scenario: Administrative API does not duplicate queries

• WHEN JournalServiceManager is inspected
• THEN artifact and revision query operations are available only through its associated JournalService

Requirement: Filesystem-backed lifecycle loading

The reference service manager SHALL own a configured existing readable root, discover runtime files only at <root>/<artifact-coordinate>/<journal-version>.journal, ignore .journal.example, validate directory and filename placement against parsed content, sort each artifact's files chronologically, read complete UTF-8 text, and supply it to the internal ingestion operation. It SHALL not create, overwrite, delete, publish, download, synchronize, or watch files.

Scenario: Valid filesystem load

• WHEN an artifact directory contains chronologically named valid genesis and successor .journal files whose content identity matches their placement
• THEN initial start or refresh ingests both complete UTF-8 texts in chronological order and exposes their chain through the service

Scenario: Example files are ignored

• WHEN a directory contains <journal-version>.journal.example
• THEN loading does not ingest it as a runtime Journal

Scenario: Invalid directory placement

• WHEN a runtime Journal's metadata-derived coordinate differs from its parent directory name
• THEN loading fails clearly

Scenario: Invalid filename placement

• WHEN a runtime filename does not use the strict timestamp syntax or differs from the parsed JOURNAL_VERSION
• THEN loading fails clearly

Scenario: Invalid root

• WHEN the configured Journal root is missing, not a directory, or unreadable
• THEN start or refresh fails clearly without creating it

Scenario: Unexpected filesystem entry

• WHEN the configured root contains a runtime entry outside the artifact-directory/revision-file structure
• THEN loading fails rather than silently treating it as a Journal

Requirement: Explicit idempotent refresh

The service manager SHALL support explicit refresh. Repeating refresh for unchanged files SHALL be idempotent, and a later refresh SHALL discover valid newly added successors while preserving existing historical revisions.

Scenario: Unchanged refresh

• WHEN refresh runs twice without filesystem changes
• THEN the second run leaves all chains unchanged and succeeds through ingestion idempotency

Scenario: New revision discovered

• WHEN a valid successor file is added after an earlier successful refresh
• THEN the next refresh ingests it and the read-only service exposes it as the new head

Requirement: Version-controlled examples and migration

Version-controlled examples SHALL use <journal-version>.journal.example beneath an artifact-coordinate directory and collectively demonstrate quoted description, a scheme-independent information URI, per-release license, dependencies, exclusions, preferences, policy, exact/range syntax, and optional descriptions. Any multi-revision example chain SHALL use the predecessor file's real exact-text SHA-256 digest.

Scenario: Example placement

• WHEN repository Journal examples are inspected
• THEN each is placed under data/nenjim/journals/<artifact-coordinate>/ with a strict Journal-version filename ending in .journal.example

Scenario: Example chain integrity

• WHEN examples include a successor revision
• THEN its predecessor digest equals the SHA-256 of the predecessor example file's exact UTF-8 bytes