81: Version fix

2026-09-03 14:36:00 +02:00
parent a65c2fc09c
commit 324aa67710
8 changed files with 37 additions and 42 deletions
@@ -52,7 +52,7 @@ Registry retains its required exceptional order of start, self-registration, the

 ### Keep deployment configuration separate from its template

-The runtime path stays a private constant in the reference Hub. `conf/NenjimHub.conf.example` is version controlled and documented, but no code references that example path. The real file remains deployment-specific under the existing `*.conf` ignore rule. Documentation shows copying explicitly and includes a separate headless snippet.
+The runtime path stays a private constant in the reference Hub. `conf/NenjimHub.conf.example` is version controlled and documented, but no code references that example path. The example deliberately contains only the mandatory Registry and Journal entries so it is safe and generic for downstream users; operators add their own deployment-specific processes and dependency order after copying it. The real file remains deployment-specific under the existing `*.conf` ignore rule. Documentation shows copying explicitly and includes the same minimal headless bootstrap.

 ## Risks / Trade-offs

@@ -64,8 +64,7 @@ The runtime path stays a private constant in the reference Hub. `conf/NenjimHub.

 ## Migration Plan

-1. Deploy the new build together with an operator-created `conf/NenjimHub.conf` copied from the version 2 example and adjusted for the deployment role.
+1. Deploy the new build together with an operator-created `conf/NenjimHub.conf` copied from the version 1 example and extended with the deployment's own ordered process selection.
 2. Validate that manually ordered dependencies precede their consumers; Registry and Journal must remain first and second.
 3. Start the Hub normally through the unchanged `Main` entry point.
 4. To roll back the software, restore the previous build and its prior deployment configuration expectations; the application never rewrites either runtime or example configuration.
-
@@ -4,20 +4,20 @@

 ## What Changes

- **BREAKING**: Require the Hub to read `conf/NenjimHub.conf` in strict format version 2 before any process starts; missing, unreadable, non-regular, malformed, or unsupported configuration fails startup without fallback.
+- **BREAKING**: Require the Hub to read `conf/NenjimHub.conf` in strict format version 1 before any process starts; missing, unreadable, non-regular, malformed, or unsupported configuration fails startup without fallback.
 - Add one mandatory ordered `[AUTO_START]` section whose active lines are canonical `NenjimComponentId` values, with defined whitespace, `#` comment, and blank-line termination rules.
 - Validate the complete requested process sequence before Registry startup, including known process capability, uniqueness, and Registry/Journal placement as the first two entries.
 - Bootstrap Registry, then eagerly construct and register the complete passive component graph, while lazily constructing, registering, and starting only the remaining configured process objects in exact configuration order.
 - Preserve registration-before-start, post-success startup recording, fail-fast partial-startup semantics, the online point, and the blocking runtime wait without rollback or dependency inference.
 - Make all modern Hub-known processes selectable, including the otherwise inactive Jupiter Perps Alarm, while an omitted process is neither constructed, registered, nor started.
- Add a documented `conf/NenjimHub.conf.example` that reproduces the former successful startup sequence and remains a copy-only template, plus headless configuration documentation.
+- Add a documented, copy-only `conf/NenjimHub.conf.example` that provides a generic minimal bootstrap with only the mandatory Registry and Journal processes, plus headless configuration documentation.
 - Remove the unconditional process-construction path and fixed startup list without adding public factory, discovery, lifecycle, Context, or configuration APIs.

 ## Capabilities

 ### New Capabilities

- `nenjim-hub-configuration`: Defines the mandatory format 2 Hub configuration grammar, validation, ordered bootstrap and startup plan, lazy selected-process construction, omitted-process behavior, template role, and failure semantics.
+- `nenjim-hub-configuration`: Defines the mandatory format 1 Hub configuration grammar, validation, ordered bootstrap and startup plan, lazy selected-process construction, omitted-process behavior, template role, and failure semantics.

 ### Modified Capabilities

@@ -29,5 +29,5 @@
 - Adds an implementation-only Hub configuration parser/model and process-construction catalogue under `com.r35157.nenjim.hubd.impl.ref` without changing the public `NenjimHub` API.
 - Refactors `NenjimHubImpl` composition so Registry remains the bootstrap exception, passive dependencies remain eager, and process instances become lazy.
 - Adds `conf/NenjimHub.conf.example` while retaining the ignored deployment-specific runtime file at `conf/NenjimHub.conf`.
- Updates Nenjim architecture and terminology documentation to describe format 2, manual dependency ordering, headless operation, and actual successful-start snapshots.
+- Updates Nenjim architecture and terminology documentation to describe format 1, manual dependency ordering, a generic minimal template, headless operation, and actual successful-start snapshots.
 - Adds no automated tests, external dependencies, process rollback, automatic dependency resolution, dynamic discovery, or command-line configuration selection.
@@ -8,7 +8,7 @@ Defines the mandatory deployment configuration that selects which modern Nenjim
 The reference Hub SHALL read only `conf/NenjimHub.conf` and SHALL complete all configuration parsing and validation before starting Registry or any other process. The path SHALL not be configurable through `Main`, command-line arguments, or the public `NenjimHub` API. A missing, unreadable, or non-regular runtime file SHALL fail Hub startup clearly and identify the configured path. The Hub SHALL not read, copy, generate, or fall back to `conf/NenjimHub.conf.example`, and SHALL not fall back to a hardcoded startup list.

 #### Scenario: Runtime configuration is valid
- **WHEN** `conf/NenjimHub.conf` is a readable regular file containing a valid format 2 configuration
+- **WHEN** `conf/NenjimHub.conf` is a readable regular file containing a valid format 1 configuration
 - **THEN** the Hub derives its complete requested process order from that file before starting Registry

 #### Scenario: Runtime configuration cannot be read
@@ -19,13 +19,13 @@ The reference Hub SHALL read only `conf/NenjimHub.conf` and SHALL complete all c
 - **WHEN** `conf/NenjimHub.conf` is absent but `conf/NenjimHub.conf.example` exists
 - **THEN** startup fails without reading, copying, or using the example and without starting a hardcoded fallback set

-### Requirement: Format 2 has one exact ordered AUTO_START section
-The first actual configuration entry SHALL be exactly `FORMAT_VERSION=2`, after optional leading blank lines and full-line comments. Version 2 SHALL be the only supported version; a missing, malformed, duplicate, version 1, or otherwise unsupported declaration SHALL fail. The next actual entry SHALL be exactly one `[AUTO_START]` header, optionally followed only by a trailing `#` comment. Unknown, malformed, repeated, valued, or out-of-order sections and entries before `[AUTO_START]` SHALL fail.
+### Requirement: Format 1 has one exact ordered AUTO_START section
+The first actual configuration entry SHALL be exactly `FORMAT_VERSION=1`, after optional leading blank lines and full-line comments. Version 1 SHALL be the only supported version; a missing, malformed, duplicate, version 2, or otherwise unsupported declaration SHALL fail. The next actual entry SHALL be exactly one `[AUTO_START]` header, optionally followed only by a trailing `#` comment. Unknown, malformed, repeated, valued, or out-of-order sections and entries before `[AUTO_START]` SHALL fail.

-Outside `[AUTO_START]`, leading and trailing whitespace SHALL be ignored, a line whose trimmed content begins with `#` SHALL be a full-line comment, and `#` after actual content SHALL begin a trailing comment. Inside `[AUTO_START]`, surrounding whitespace around a process ID SHALL be ignored; full-line and trailing comments SHALL be ignored; comment-only lines SHALL not terminate the section; and the first whitespace-only line or end of file SHALL terminate it. After termination, only blank lines and comments SHALL be accepted. Format 2 SHALL provide no quoting or escaping for `#`.
+Outside `[AUTO_START]`, leading and trailing whitespace SHALL be ignored, a line whose trimmed content begins with `#` SHALL be a full-line comment, and `#` after actual content SHALL begin a trailing comment. Inside `[AUTO_START]`, surrounding whitespace around a process ID SHALL be ignored; full-line and trailing comments SHALL be ignored; comment-only lines SHALL not terminate the section; and the first whitespace-only line or end of file SHALL terminate it. After termination, only blank lines and comments SHALL be accepted. Format 1 SHALL provide no quoting or escaping for `#`.

 #### Scenario: Leading comments and trailing comments are accepted
- **WHEN** blank lines or full-line comments precede `FORMAT_VERSION=2`, and the version, section header, or process entries contain trailing `#` comments
+- **WHEN** blank lines or full-line comments precede `FORMAT_VERSION=1`, and the version, section header, or process entries contain trailing `#` comments
 - **THEN** comment text and permitted surrounding whitespace are ignored while the actual entries are parsed normally

 #### Scenario: Comment inside AUTO_START does not terminate it
@@ -41,7 +41,7 @@ Outside `[AUTO_START]`, leading and trailing whitespace SHALL be ignored, a line
 - **THEN** the section terminates successfully at end of file

 #### Scenario: Version declaration is invalid
- **WHEN** the version is absent, malformed, duplicated, not the first actual entry, or has a value other than `2`
+- **WHEN** the version is absent, malformed, duplicated, not the first actual entry, or has a value other than `1`
 - **THEN** configuration validation fails before any process starts and identifies the path, relevant line and reason

 #### Scenario: Section structure is invalid
@@ -127,13 +127,12 @@ Registry and every selected process SHALL be registered before its `start()` cal
 - **THEN** the startup snapshot has the exact configured order, the online point is announced, and the Hub enters its existing blocking wait

 ### Requirement: The version-controlled example is a copy-only template
-The repository SHALL contain `conf/NenjimHub.conf.example` as a documented format 2 template that reproduces the former successful process sequence without selecting `jupiter-perps-alarm.default`. Its comments SHALL state that Registry and Journal are mandatory, order is preserved, current process dependencies must be listed manually before consumers, JavaFX runtime precedes JavaFX applications, commenting out an entry prevents its process from being constructed or started, and the file must be copied to `conf/NenjimHub.conf` before use. Documentation SHALL include a headless example and SHALL describe recursive dependency construction as future work rather than implemented behavior.
+The repository SHALL contain `conf/NenjimHub.conf.example` as a documented format 1 copy-only template with only the mandatory Registry and Journal entries active. It SHALL contain no optional deployment-specific process IDs. Its comments SHALL state that the file must be copied to `conf/NenjimHub.conf` before use, Registry and Journal are mandatory, order is preserved, and process dependencies must be listed manually before their consumers. Documentation SHALL show the same minimal bootstrap as a headless example and SHALL describe recursive dependency construction as future work rather than implemented behavior.

-#### Scenario: Example reproduces the former startup sequence
+#### Scenario: Example provides a generic minimal bootstrap
 - **WHEN** the example's uncommented process IDs are read in order
- **THEN** they are Registry, Journal, Ticker, Production Evelyn, Test Evelyn, Production IOU Burner, JavaFX runtime, Mission Control, and Process Manager
+- **THEN** they are only Registry and Journal, with no optional deployment-specific process ID present

-#### Scenario: Operator uses a headless example
+#### Scenario: Operator uses the minimal headless example
 - **WHEN** the documented headless configuration is copied to the runtime path
- **THEN** it selects Registry, Journal, Ticker, Production Evelyn, and Production IOU Burner without selecting Test Evelyn or any JavaFX process
-
+- **THEN** it selects only Registry and Journal and leaves every optional process for the operator to add explicitly
@@ -1,6 +1,6 @@
 ## 1. Hub configuration

- [x] 1.1 Add the package-private immutable Hub configuration model and strict format 2 parser for the fixed runtime path, including exact version/section/comment/termination grammar and path-and-line diagnostics.
+- [x] 1.1 Add the package-private immutable Hub configuration model and strict format 1 parser for the fixed runtime path, including exact version/section/comment/termination grammar and path-and-line diagnostics.
 - [x] 1.2 Validate canonical process IDs, duplicates, known process construction capability, and mandatory Registry/Journal positions before Registry startup.

 ## 2. Ordered runtime composition
@@ -11,7 +11,7 @@

 ## 3. Configuration template and documentation

- [x] 3.1 Add `conf/NenjimHub.conf.example` as a documented copy-only format 2 template reproducing the former startup sequence without enabling Jupiter Perps Alarm.
+- [x] 3.1 Add `conf/NenjimHub.conf.example` as a documented copy-only format 1 template containing only the mandatory Registry and Journal bootstrap entries, without deployment-specific optional processes.
 - [x] 3.2 Update Nenjim architecture, public documentation, and terminology for mandatory Hub configuration, exact grammar, manual dependency order, passive versus selected construction, omission, failure semantics, and headless operation.

 ## 4. Verification