78: Make JournalService a Hub-managed Nenjim process and integrate it into startup
This commit is contained in:
+2
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-09-02
|
||||
@@ -0,0 +1,123 @@
|
||||
## Context
|
||||
|
||||
Issue #75 implemented a strict filesystem-backed Journal and put construction,
|
||||
initial loading, service access, refresh and stop on `JournalServiceManager`.
|
||||
Issue #77 subsequently established a common runtime architecture: the Hub
|
||||
constructs and starts active `NenjimProcess` objects, domain service interfaces
|
||||
stay lifecycle-free, and service managers are separate passive administrative
|
||||
handles retained by the Hub.
|
||||
|
||||
The Journal format, parser, exact-text digest, chain validation, immutable
|
||||
queries and explicit refresh behavior are already accepted and must remain
|
||||
unchanged. Only ownership, lifecycle placement and Hub integration change.
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
|
||||
- Preserve one read-only registrable `JournalService` domain interface.
|
||||
- Make the same Journal object available as the canonical `NenjimProcess`.
|
||||
- Publish no queryable initial state until the complete filesystem load
|
||||
succeeds.
|
||||
- Keep refresh available only through a distinct passive manager.
|
||||
- Start and record Journal second, after Registry and before business
|
||||
composition/startup.
|
||||
- Keep runtime files read-only and `.journal.example` files ignored.
|
||||
|
||||
**Non-Goals:**
|
||||
|
||||
- Journal format, model, parser, chain or policy redesign.
|
||||
- Background watching, polling or remote synchronization.
|
||||
- Generic stop, restart, health, rollback or recovery.
|
||||
- Context, resolution, classloading, artifact transfer, configurable autorun or
|
||||
Process Manager integration.
|
||||
- New general unit tests or production test hooks.
|
||||
|
||||
## Decisions
|
||||
|
||||
### One hidden service implementation provides service, process and admin views
|
||||
|
||||
`JournalServiceImpl` remains under `.impl.ref` and becomes package-private. It
|
||||
implements public `JournalService`, public `NenjimProcess`, and a new
|
||||
package-private `JournalServiceAdmin`. Keeping the concrete type and admin view
|
||||
non-public prevents ordinary service consumers from naming and casting to the
|
||||
filesystem administration contract.
|
||||
|
||||
`JournalServiceAssembly.create(Path)` constructs one service object, exposes it
|
||||
through identity-preserving service and process views, and constructs one
|
||||
distinct `JournalServiceManagerImpl` against its admin view. The assembly owns
|
||||
no lifecycle and exposes no reverse path from an active service reference to
|
||||
its manager.
|
||||
|
||||
### The service process owns a single startup attempt
|
||||
|
||||
The configured root is normalized once during service construction. An atomic
|
||||
start-attempt guard is consumed before filesystem work, so every second
|
||||
`start()` call fails with `IllegalStateException`, including after a failed
|
||||
first attempt. Queries check a volatile availability gate and fail with
|
||||
`IllegalStateException` until startup has succeeded.
|
||||
|
||||
### Initial loading is all-or-nothing
|
||||
|
||||
Startup loads every runtime file into a private candidate Journal service using
|
||||
the existing parser and ingestion rules. Only after the loader has completed
|
||||
does the active object copy the candidate's immutable chains and digest index
|
||||
under its state lock and open the availability gate. A root, layout, parse or
|
||||
chain failure therefore propagates unchanged and leaves the active service with
|
||||
no queryable partial worldview.
|
||||
|
||||
Extracting a separate new mutable chain-store abstraction was rejected because
|
||||
it would broaden a lifecycle refactor into a Journal-domain redesign. The
|
||||
candidate uses the already accepted ingestion implementation and is never
|
||||
published.
|
||||
|
||||
### Filesystem loading belongs behind the service admin boundary
|
||||
|
||||
The existing strict loader logic moves from the manager into a package-private
|
||||
`JournalFilesystemLoader`. The Journal process invokes it for initial loading;
|
||||
the manager delegates refresh through `JournalServiceAdmin`. The loader keeps
|
||||
the exact root/layout/readability checks, deterministic ordering, placement
|
||||
validation, `.journal.example` exclusion and no-write behavior.
|
||||
|
||||
Post-start refresh loads into the active service and deliberately preserves the
|
||||
existing per-ingestion atomicity and idempotency. The issue does not strengthen
|
||||
refresh into whole-filesystem transactional replacement.
|
||||
|
||||
### Hub starts Journal as infrastructure before the business graph
|
||||
|
||||
After Registry start, registration and successful-history recording,
|
||||
`NenjimHubImpl` creates the Journal assembly for `data/nenjim/journals`, retains
|
||||
its manager, registers the service as `nenjim.journal.service`, starts its
|
||||
process view, and records the ID only after `start()` returns. Business graph
|
||||
construction and the existing enabled startup sequence occur only afterwards.
|
||||
|
||||
Consequently, a Journal failure propagates from the Hub while the Registry is
|
||||
the sole recorded process. The Hub neither constructs/starts later business
|
||||
processes nor reaches its online point or blocking wait. No rollback is added
|
||||
because the common process contract has no stop operation.
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- [The hidden implementation was formerly public] → No accepted public API
|
||||
signature returns it; the assembly exposes only public interfaces and keeps
|
||||
the documented implementation boundary intact.
|
||||
- [Loading through a candidate duplicates temporary in-memory state] → Startup
|
||||
happens once and Journal data is expected to be modest; the temporary cost
|
||||
buys clear all-or-nothing publication without changing domain semantics.
|
||||
- [Refresh can accept an earlier new revision before a later file fails] → This
|
||||
is the already specified per-ingestion atomic behavior and is intentionally
|
||||
preserved.
|
||||
- [The Hub's successful path blocks indefinitely] → Verify Journal lifecycle,
|
||||
identity, boundaries and sample-root loading with temporary probes rather
|
||||
than invoking production `main()`.
|
||||
|
||||
## Migration Plan
|
||||
|
||||
1. Change Journal contracts and add the internal admin, loader and assembly
|
||||
boundary.
|
||||
2. Move startup into the service process and reduce the manager to passive
|
||||
delegation.
|
||||
3. Register/start Journal in the Hub before business composition and startup.
|
||||
4. Update OpenSpec and directly affected documentation.
|
||||
5. Run strict OpenSpec validation, the complete Gradle build and safe temporary
|
||||
boundary/lifecycle probes, then leave this change active for review.
|
||||
@@ -0,0 +1,40 @@
|
||||
## Why
|
||||
|
||||
Issue #75 left the Journal subsystem on a manager-owned lifecycle, while issue
|
||||
#77 established `NenjimHub` as the runtime owner and `NenjimProcess` as the
|
||||
canonical active lifecycle. Journal must use that common model before later
|
||||
runtime work can depend on it consistently.
|
||||
|
||||
## What Changes
|
||||
|
||||
- Make `JournalService` a registrable Nenjim component while keeping its query
|
||||
API read-only and filesystem-independent.
|
||||
- Make the reference Journal service object the single-use active
|
||||
`NenjimProcess`, with atomic publication after a complete successful initial
|
||||
filesystem load.
|
||||
- Reduce `JournalServiceManager` to the passive `journalRoot()` and `refresh()`
|
||||
administrative capability, bound through a non-public admin view.
|
||||
- Add an implementation-only Journal assembly that provides identical service
|
||||
and process views plus a distinct manager.
|
||||
- Have `NenjimHubImpl` register and start `nenjim.journal.service` immediately
|
||||
after the Registry and before every business process.
|
||||
- Preserve Journal format, parsing, chain, query, refresh and filesystem
|
||||
semantics while updating directly affected documentation.
|
||||
|
||||
## Capabilities
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
- `nenjim-journal-management`: move lifecycle and initial loading from the
|
||||
manager to the service process, add startup query gating and the safe
|
||||
construction boundary, and preserve explicit refresh.
|
||||
- `nenjim-component-registry`: extend Hub-owned composition, startup order,
|
||||
started-process history and fail-fast behavior with the Journal process.
|
||||
|
||||
## Impact
|
||||
|
||||
Affected code is limited to the Journal public contracts and reference
|
||||
implementation, the Hub composition root, directly affected architecture
|
||||
documentation, and this active OpenSpec change. No Journal data format,
|
||||
business-service behavior, configurable autorun, stop lifecycle, Context,
|
||||
resolver, classloader, watcher or general test suite is added.
|
||||
+44
@@ -0,0 +1,44 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: NenjimHub owns composition and runtime startup
|
||||
`NenjimHub` SHALL be the global runtime owner and SHALL expose `start() throws Exception` plus an immutable ordered snapshot of successfully started process IDs. It SHALL be neither a component nor a process and SHALL not register itself. Its only accepted startup attempt SHALL construct the Registry subsystem, start the Registry process first, register it as `nenjim.registry.service`, construct and register the Journal subsystem as `nenjim.journal.service`, start Journal second, and continue to the complete hardcoded business component set from issue #76 only after Journal startup succeeds. The Hub SHALL then resolve only the explicitly enabled business IDs through `NenjimProcess`, start them in dependency-safe order, announce the existing online point, and preserve the existing blocking wait. Registration SHALL never imply startup, and both the Registry and Journal managers SHALL remain distinct passive, unregistered handles retained privately by the Hub.
|
||||
|
||||
#### Scenario: Registry starts before graph construction
|
||||
- **WHEN** the Hub performs its first startup attempt
|
||||
- **THEN** it starts, registers and records Registry first, before constructing Journal or components in the business graph
|
||||
|
||||
#### Scenario: Journal starts before business composition
|
||||
- **WHEN** Registry startup and self-registration have succeeded
|
||||
- **THEN** the Hub registers, starts and records Journal before constructing components in the business graph
|
||||
|
||||
#### Scenario: Registry is process-discoverable
|
||||
- **WHEN** the Registry registration has completed
|
||||
- **THEN** the same object is retrievable as both `NenjimRegistryService` and `NenjimProcess`
|
||||
|
||||
#### Scenario: Journal is process-discoverable
|
||||
- **WHEN** the Journal registration has completed
|
||||
- **THEN** the same object is retrievable as both `JournalService` and `NenjimProcess` under `nenjim.journal.service`, while its manager is not registered
|
||||
|
||||
#### Scenario: Required hardcoded bindings are registered
|
||||
- **WHEN** Hub composition completes
|
||||
- **THEN** Journal and all component IDs and implementation choices enumerated by issue #76 are present exactly as configured, including intentionally inactive components and excluding both service managers
|
||||
|
||||
#### Scenario: Explicit startup subset preserves order
|
||||
- **WHEN** Hub startup succeeds through the business-process phase
|
||||
- **THEN** successful process order is `nenjim.registry.service`, `nenjim.journal.service`, `assetaz.ticker.default`, `evelyn.service.prod`, `evelyn.service.test`, `evelyn.iou-burner.prod`, and `evelyn.mission-control.default`
|
||||
|
||||
#### Scenario: Deliberately inactive processes remain inactive
|
||||
- **WHEN** Hub startup reaches its online point
|
||||
- **THEN** `jupiter-perps-alarm.default` and the dormant Composer, Process Manager, Test Tool, Soda Task Manager, and Suwimo Client paths have not been started
|
||||
|
||||
#### Scenario: Journal failure is fail-fast
|
||||
- **WHEN** Journal process startup throws
|
||||
- **THEN** Registry remains the only recorded process, no business component is constructed or started, the exception propagates, and the Hub neither announces online nor enters its final wait
|
||||
|
||||
#### Scenario: Hub start is not retried
|
||||
- **WHEN** any first Hub startup attempt has begun and `start()` is requested again
|
||||
- **THEN** the later request fails with `IllegalStateException` whether the first attempt succeeded or failed
|
||||
|
||||
#### Scenario: Startup failure is fail-fast
|
||||
- **WHEN** any process startup throws
|
||||
- **THEN** the exception propagates, no later process starts, the Hub neither announces online nor enters its final wait, and no generic rollback or retry is attempted
|
||||
+124
@@ -0,0 +1,124 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### 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
|
||||
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Filesystem-independent read-only Journal service
|
||||
`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 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
|
||||
- **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 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 is registrable as a component but provides no start, stop, filesystem root, refresh, parsing, update, ingestion, administration or other mutation operation
|
||||
|
||||
### Requirement: Filesystem-backed lifecycle loading
|
||||
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 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`
|
||||
- **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** 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 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 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 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
|
||||
|
||||
## REMOVED Requirements
|
||||
|
||||
### Requirement: Journal service lifecycle manager
|
||||
**Reason**: Lifecycle ownership belongs to the Journal service object as a Hub-managed `NenjimProcess`; the manager is only a passive administrative capability.
|
||||
|
||||
**Migration**: The Hub starts the Journal through its process view and retains a distinct manager exposing only `journalRoot()` and `refresh()`.
|
||||
@@ -0,0 +1,24 @@
|
||||
## 1. Journal contracts and construction boundary
|
||||
|
||||
- [x] 1.1 Make `JournalService` a registrable component without adding lifecycle or administration to its query API.
|
||||
- [x] 1.2 Reduce `JournalServiceManager` to `journalRoot()` and `refresh()` and remove lifecycle/service-access compatibility methods.
|
||||
- [x] 1.3 Add the package-private Journal admin and filesystem-loader boundary plus an implementation-only assembly with identity-preserving service/process views.
|
||||
|
||||
## 2. Journal lifecycle and Hub integration
|
||||
|
||||
- [x] 2.1 Make the hidden reference service a single-attempt `NenjimProcess` with query gating and all-or-nothing initial-state publication.
|
||||
- [x] 2.2 Preserve strict read-only filesystem discovery, chronological ingestion, `.journal.example` exclusion and explicit idempotent refresh.
|
||||
- [x] 2.3 Construct, register, start and record `nenjim.journal.service` after Registry and before the existing business graph while retaining the passive manager privately.
|
||||
|
||||
## 3. OpenSpec and documentation
|
||||
|
||||
- [x] 3.1 Add Journal-management deltas for the process lifecycle, passive manager, construction boundary, startup availability and preserved refresh semantics.
|
||||
- [x] 3.2 Extend Hub runtime requirements with Journal registration, second-process ordering and fail-fast behavior.
|
||||
- [x] 3.3 Update directly affected Markdown, terminology, public HTML and JavaDoc to describe the common service/process/manager model.
|
||||
|
||||
## 4. Verification
|
||||
|
||||
- [x] 4.1 Strictly validate this active change and all repository specifications without synchronizing or archiving it.
|
||||
- [x] 4.2 Run the complete Gradle clean build without invoking production `main()`.
|
||||
- [x] 4.3 Use removable probes to verify view identity, pre-start/failed-start query gating, one-shot startup, example-only empty startup, refresh and non-public administration.
|
||||
- [x] 4.4 Audit the final diff, generated-source references, acceptance criteria and out-of-scope boundaries without committing or pushing.
|
||||
@@ -186,34 +186,46 @@ The reference Registry construction boundary SHALL create one Registry object ex
|
||||
- **THEN** no component ID identifies the manager and no lookup returns it as a component or process
|
||||
|
||||
### Requirement: NenjimHub owns composition and runtime startup
|
||||
`NenjimHub` SHALL be the global runtime owner and SHALL expose `start() throws Exception` plus an immutable ordered snapshot of successfully started process IDs. It SHALL be neither a component nor a process and SHALL not register itself. Its only accepted startup attempt SHALL construct the Registry subsystem, start the Registry process first, register it as `nenjim.registry.service`, construct and register the complete hardcoded component set from issue #76 in dependency order, resolve only the explicitly enabled IDs through `NenjimProcess`, start them in dependency-safe order, announce the existing online point, and preserve the existing blocking wait. Registration SHALL never imply startup.
|
||||
`NenjimHub` SHALL be the global runtime owner and SHALL expose `start() throws Exception` plus an immutable ordered snapshot of successfully started process IDs. It SHALL be neither a component nor a process and SHALL not register itself. Its only accepted startup attempt SHALL construct the Registry subsystem, start the Registry process first, register it as `nenjim.registry.service`, construct and register the Journal subsystem as `nenjim.journal.service`, start Journal second, and continue to the complete hardcoded business component set from issue #76 only after Journal startup succeeds. The Hub SHALL then resolve only the explicitly enabled business IDs through `NenjimProcess`, start them in dependency-safe order, announce the existing online point, and preserve the existing blocking wait. Registration SHALL never imply startup, and both the Registry and Journal managers SHALL remain distinct passive, unregistered handles retained privately by the Hub.
|
||||
|
||||
#### Scenario: Registry starts before graph construction
|
||||
- **WHEN** the Hub performs its first startup attempt
|
||||
- **THEN** it starts the Registry, registers it as `nenjim.registry.service`, and records that ID before constructing components whose constructors may query the Registry
|
||||
- **THEN** it starts, registers and records Registry first, before constructing Journal or components in the business graph
|
||||
|
||||
#### Scenario: Journal starts before business composition
|
||||
- **WHEN** Registry startup and self-registration have succeeded
|
||||
- **THEN** the Hub registers, starts and records Journal before constructing components in the business graph
|
||||
|
||||
#### Scenario: Registry is process-discoverable
|
||||
- **WHEN** the Registry registration has completed
|
||||
- **THEN** the same object is retrievable as both `NenjimRegistryService` and `NenjimProcess`
|
||||
|
||||
#### Scenario: Journal is process-discoverable
|
||||
- **WHEN** the Journal registration has completed
|
||||
- **THEN** the same object is retrievable as both `JournalService` and `NenjimProcess` under `nenjim.journal.service`, while its manager is not registered
|
||||
|
||||
#### Scenario: Required hardcoded bindings are registered
|
||||
- **WHEN** Hub composition completes
|
||||
- **THEN** all component IDs and implementation choices enumerated by issue #76 are present exactly as configured, including intentionally inactive components and excluding the former Registry-manager ID
|
||||
- **THEN** Journal and all component IDs and implementation choices enumerated by issue #76 are present exactly as configured, including intentionally inactive components and excluding both service managers
|
||||
|
||||
#### Scenario: Explicit startup subset preserves order
|
||||
- **WHEN** the Hub starts processes after the Registry
|
||||
- **THEN** it starts `assetaz.ticker.default`, `evelyn.service.prod`, `evelyn.service.test`, `evelyn.iou-burner.prod`, and `evelyn.mission-control.default` in that order
|
||||
- **WHEN** Hub startup succeeds through the business-process phase
|
||||
- **THEN** successful process order is `nenjim.registry.service`, `nenjim.journal.service`, `assetaz.ticker.default`, `evelyn.service.prod`, `evelyn.service.test`, `evelyn.iou-burner.prod`, and `evelyn.mission-control.default`
|
||||
|
||||
#### Scenario: Deliberately inactive processes remain inactive
|
||||
- **WHEN** Hub startup reaches its online point
|
||||
- **THEN** `jupiter-perps-alarm.default` and the dormant Composer, Process Manager, Test Tool, Soda Task Manager, and Suwimo Client paths have not been started
|
||||
|
||||
#### Scenario: Journal failure is fail-fast
|
||||
- **WHEN** Journal process startup throws
|
||||
- **THEN** Registry remains the only recorded process, no business component is constructed or started, the exception propagates, and the Hub neither announces online nor enters its final wait
|
||||
|
||||
#### Scenario: Hub start is not retried
|
||||
- **WHEN** any first Hub startup attempt has begun and `start()` is requested again
|
||||
- **THEN** the later request fails with `IllegalStateException` whether the first attempt succeeded or failed
|
||||
|
||||
#### Scenario: Startup failure is fail-fast
|
||||
- **WHEN** a process startup throws
|
||||
- **WHEN** any process startup throws
|
||||
- **THEN** the exception propagates, no later process starts, the Hub neither announces online nor enters its final wait, and no generic rollback or retry is attempted
|
||||
|
||||
### Requirement: Started-process snapshots are ordered immutable and truthful
|
||||
|
||||
@@ -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