78: Make JournalService a Hub-managed Nenjim process and integrate it into startup
This commit is contained in:
@@ -3,10 +3,7 @@
|
||||
## 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.
|
||||
|
||||
@@ -23,10 +20,10 @@ The public Journal API SHALL begin at `com.r35157.nenjim.service.journal`, where
|
||||
- **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.
|
||||
`JournalService` SHALL extend `NenjimComponent` as the ordinary registrable, 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, administration or mutation operation. Its queries SHALL be available only after the Journal process has completed successful startup.
|
||||
|
||||
#### Scenario: Chronological and latest queries
|
||||
- **WHEN** an artifact has several accepted revisions
|
||||
- **WHEN** an artifact has several accepted revisions after successful startup
|
||||
- **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
|
||||
@@ -38,12 +35,12 @@ The public Journal API SHALL begin at `com.r35157.nenjim.service.journal`, where
|
||||
- **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
|
||||
- **WHEN** a coordinate, revision, as-of revision, or artifact release is unknown after successful startup
|
||||
- **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
|
||||
- **THEN** the interface is registrable as a component but provides no start, stop, filesystem root, refresh, parsing, update, ingestion, administration 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.
|
||||
@@ -90,35 +87,12 @@ Supplying the same coordinate, Journal version, and exact complete text more tha
|
||||
- **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.
|
||||
The reference Journal service process SHALL own a configured existing readable root and SHALL use non-public filesystem loading to 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 existing internal ingestion operation. Initial loading SHALL publish only after the complete root succeeds. Later refresh SHALL target the active service through its non-public administration view. Neither path SHALL 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
|
||||
- **THEN** initial process startup or a later explicit 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`
|
||||
@@ -134,23 +108,27 @@ The reference service manager SHALL own a configured existing readable root, dis
|
||||
|
||||
#### Scenario: Invalid root
|
||||
- **WHEN** the configured Journal root is missing, not a directory, or unreadable
|
||||
- **THEN** start or refresh fails clearly without creating it
|
||||
- **THEN** startup 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.
|
||||
The passive service manager SHALL support explicit refresh only after successful Journal process startup. Repeating refresh for unchanged files SHALL be idempotent, and a later refresh SHALL discover valid newly added successors while preserving existing historical revisions and the existing per-ingestion atomicity.
|
||||
|
||||
#### Scenario: Unchanged refresh
|
||||
- **WHEN** refresh runs twice without filesystem changes
|
||||
- **WHEN** refresh runs twice after startup 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
|
||||
- **WHEN** a valid successor file is added after successful startup or an earlier refresh
|
||||
- **THEN** the next refresh ingests it and the read-only service exposes it as the new head
|
||||
|
||||
#### Scenario: Refresh is not a service operation
|
||||
- **WHEN** ordinary consumers inspect `JournalService` and `NenjimProcess`
|
||||
- **THEN** neither interface exposes refresh
|
||||
|
||||
### 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.
|
||||
|
||||
@@ -161,3 +139,52 @@ Version-controlled examples SHALL use `<journal-version>.journal.example` beneat
|
||||
#### 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
|
||||
|
||||
### Requirement: Journal construction preserves process identity and administration boundaries
|
||||
The reference Journal construction boundary SHALL create one Journal object configured with a normalized absolute data root and exposed through both `JournalService` and `NenjimProcess`, plus one distinct `JournalServiceManager` bound to that object through a package-private administration view. The service and process views SHALL preserve object identity. The construction helper SHALL own no lifecycle, SHALL be neither a component nor a process, SHALL not be registered, and SHALL expose neither parser, ingestion, chain state, filesystem administration nor a way to derive the active Journal's manager from an ordinary service reference.
|
||||
|
||||
#### Scenario: Journal views preserve identity
|
||||
- **WHEN** the Hub obtains a newly constructed Journal assembly
|
||||
- **THEN** its service and process views reference the identical Journal object while its manager is a different object
|
||||
|
||||
#### Scenario: Ordinary service reference remains read-only
|
||||
- **WHEN** an ordinary consumer receives the public Journal service view
|
||||
- **THEN** the consumer cannot name or derive the package-private administration view or obtain the manager bound to that active Journal
|
||||
|
||||
### Requirement: Journal process startup is single-use and publishes atomically
|
||||
The reference Journal service object SHALL implement `NenjimProcess`. Its first `start()` call SHALL be the only accepted attempt, SHALL load only its construction-configured root, and SHALL make query state available only after the complete initial filesystem load succeeds. A later start SHALL fail with `IllegalStateException`, including after a failed first attempt. Queries before successful startup or after failed startup SHALL fail with `IllegalStateException`, and no failed initial load SHALL expose a partial Journal worldview.
|
||||
|
||||
#### Scenario: Successful initial process start
|
||||
- **WHEN** the configured root and every runtime Journal entry are valid
|
||||
- **THEN** the process returns only after the complete chronological load is queryable
|
||||
|
||||
#### Scenario: Example-only root starts empty
|
||||
- **WHEN** the configured root exists and contains only valid artifact directories with `.journal.example` files
|
||||
- **THEN** process startup succeeds and the service exposes an empty immutable coordinate set
|
||||
|
||||
#### Scenario: Query before successful startup
|
||||
- **WHEN** any Journal query is called before startup succeeds or after startup fails
|
||||
- **THEN** it fails with `IllegalStateException` and exposes no candidate state
|
||||
|
||||
#### Scenario: Failed startup is not retried
|
||||
- **WHEN** the first Journal process start fails and `start()` is called again
|
||||
- **THEN** the second call fails with `IllegalStateException` without another loading attempt
|
||||
|
||||
#### Scenario: Failed initial load publishes nothing
|
||||
- **WHEN** an earlier runtime entry is valid but any later entry fails root, layout, parsing, placement or chain validation
|
||||
- **THEN** the original meaningful failure propagates and no accepted candidate revision becomes queryable
|
||||
|
||||
### Requirement: Passive Journal service manager
|
||||
`JournalServiceManager` SHALL expose exactly the normalized configured `journalRoot()` and explicit `refresh()` administration operations. It SHALL be neither a Nenjim component nor a Nenjim process, SHALL be retained privately by the Hub, SHALL bind to exactly one Journal object through non-public administration, and SHALL expose no start, stop, service accessor, query, parser, ingestion or chain-state operation. Refresh before successful Journal process startup SHALL fail with `IllegalStateException`.
|
||||
|
||||
#### Scenario: Manager contract is passive
|
||||
- **WHEN** the public manager interface and reference manager are inspected
|
||||
- **THEN** only root reporting and refresh are available and the manager has no lifecycle or component identity
|
||||
|
||||
#### Scenario: Refresh follows process startup
|
||||
- **WHEN** refresh is requested before its Journal process has started successfully
|
||||
- **THEN** the manager rejects it with `IllegalStateException`
|
||||
|
||||
#### Scenario: Manager delegates after startup
|
||||
- **WHEN** refresh is requested after successful Journal startup
|
||||
- **THEN** the manager delegates through the non-public admin view to the same active Journal object
|
||||
|
||||
Reference in New Issue
Block a user