81: Control Nenjim process construction and ordered startup through NenjimHub.conf
This commit is contained in:
+2
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-09-03
|
||||
@@ -0,0 +1,70 @@
|
||||
## Context
|
||||
|
||||
See `proposal.md` for motivation and the delta specifications for observable behavior. `NenjimHubImpl` currently mixes passive and active construction in shared initialization methods, then resolves and starts a fixed list of already-registered processes. Registry is the bootstrap exception, Journal currently starts before the rest of composition, and process dependencies are retained as concrete Hub fields.
|
||||
|
||||
The change must keep the public Hub, Registry, process, Journal, and JavaFX APIs unchanged. Human-written Java remains under `src/main/tjava`; Detag remains part of the normal Gradle build. Issue #81 excludes general automated tests, so verification uses strict OpenSpec validation, source inspection, and the complete Gradle build without running the production Hub.
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
|
||||
- Make configuration parsing and all statically knowable validation complete before Registry startup.
|
||||
- Make the passive/process boundary visible in composition structure and ensure no process constructor runs in the passive phase.
|
||||
- Represent process construction capability without preconstructing instances or encoding a second startup order.
|
||||
- Preserve the existing component IDs, concrete implementations, injected dependencies, single-attempt lifecycle, startup snapshots, online point, and wait behavior.
|
||||
- Let missing predecessor processes fail through the existing constructor/start contracts without adding implicit dependency behavior.
|
||||
|
||||
**Non-Goals:**
|
||||
|
||||
- No reusable public configuration framework, process factory, graph resolver, dependency metadata, test hook, or alternative Hub constructor.
|
||||
- No refactoring of embedded operational configuration unrelated to process selection.
|
||||
- No cleanup of legacy Hub/process prototypes and no change to component-specific lifecycle behavior.
|
||||
|
||||
## Decisions
|
||||
|
||||
### Parse into one immutable internal startup plan
|
||||
|
||||
Add a package-private Hub configuration value and parser under `com.r35157.nenjim.hubd.impl.ref`. The parser reads `conf/NenjimHub.conf` as UTF-8, checks file kind/readability, and returns an immutable ordered list of canonical `NenjimComponentId` values. It receives the implementation's known selectable ID set so syntax, duplicates, capability, and mandatory placement are all rejected in one pre-start phase.
|
||||
|
||||
The parser uses an explicit state machine for before-version, before-section, inside-section, and after-section states. It distinguishes a whitespace-only source line from a comment-only line before removing trailing `#` content, which preserves the issue's unusual rule that blank lines terminate `[AUTO_START]` while comments do not. Error helpers attach path and one-based line details consistently.
|
||||
|
||||
Using the existing general format-version validator was considered. It does not by itself model section termination and would require a parallel preprocessing/state layer; keeping the complete grammar in the Hub parser avoids two competing interpretations and permits more precise diagnostics.
|
||||
|
||||
### Use a constructor catalogue, not an autorun list
|
||||
|
||||
`NenjimHubImpl` owns an implementation-only map from every non-Registry selectable process ID to a no-argument constructor operation. Bound method references describe capability but do not create process instances. Registry remains an explicit bootstrap exception and is added only to the known-ID validation set. Map iteration order is never used; the validated configuration list is the sole startup order.
|
||||
|
||||
A switch statement was considered but would scatter selection, construction, and validation membership. A public or Registry-provided factory was rejected because discovery and extension APIs are outside scope.
|
||||
|
||||
### Split eager passive composition from lazy process construction
|
||||
|
||||
Existing building blocks, price sources, Jupiter services, the swap service, and notification service remain eagerly constructed and registered after Registry startup. Ticker, both Evelyn services, the Burner, Jupiter Perps Alarm, JavaFX runtime, Mission Control, Process Manager, and Journal move to individual lazy constructor operations because their concrete implementations participate in `NenjimProcess`.
|
||||
|
||||
Each lazy operation assigns the same Hub field used by downstream constructors, but returns the newly constructed canonical process before registration. This preserves current dependency wiring: for example, Evelyn construction fails if Ticker has not already been selected, and Mission Control fails if its configured Evelyn or JavaFX predecessors are absent. No null placeholder is registered and no constructor is invoked speculatively.
|
||||
|
||||
Journal's lazy operation also retains its passive manager from the assembly. The Registry assembly remains special because Registry must start before any ordinary registration can be queried.
|
||||
|
||||
### Apply one registration-before-start path to configured processes
|
||||
|
||||
For each configured ID after Registry, the Hub looks up its constructor operation, constructs the process, registers it under the configured ID, resolves the registered object through `NenjimProcess`, starts it, and records the ID only after successful return. A constructor failure therefore precedes registration; a start failure can leave the registered instance visible but cannot enter the successful-start snapshot. Exceptions propagate immediately, so later map entries are irrelevant and later configured IDs are untouched.
|
||||
|
||||
Registry retains its required exceptional order of start, self-registration, then recording. The online announcement and blocking wait remain after the configuration loop only.
|
||||
|
||||
### 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 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
|
||||
|
||||
- [Constructor-order coupling remains implicit in fields] → Document that `[AUTO_START]` is the complete manual dependency closure and keep failures clear; dependency metadata is intentionally deferred.
|
||||
- [A selected process constructor may assign a Hub field before later registration fails] → Do not retry or roll back; fail-fast startup is single-attempt and the Registry remains the observable boundary.
|
||||
- [Parser edge cases around comments and blank lines are easy to conflate] → Decide termination from the original trimmed line before trailing-comment removal and keep parser states explicit.
|
||||
- [A future process may be added to construction but forgotten in validation] → Derive known non-Registry IDs from the same constructor catalogue used at runtime and add Registry programmatically.
|
||||
- [Headless verification could accidentally initialize JavaFX] → Do not run the production Hub during verification; inspect constructor placement and rely on the complete compilation/build path.
|
||||
|
||||
## Migration Plan
|
||||
|
||||
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.
|
||||
@@ -0,0 +1,33 @@
|
||||
## Why
|
||||
|
||||
`NenjimHubImpl` currently constructs the complete active process graph and starts a fixed process sequence, so one build cannot serve deployment roles such as a headless server without also constructing JavaFX processes. Issue #81 introduces an explicit, validated deployment configuration now, while process dependency discovery and recursive construction remain future work.
|
||||
|
||||
## What Changes
|
||||
|
||||
- **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, 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 1 Hub configuration grammar, validation, ordered bootstrap and startup plan, lazy selected-process construction, omitted-process behavior, template role, and failure semantics.
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
- `nenjim-component-registry`: Replaces the Hub's complete hardcoded process graph and fixed startup subset with eager passive registration plus configuration-selected process construction and registration.
|
||||
- `javafx-runtime-service`: Replaces the fixed Hub ordering guarantee with explicit dependency-safe configuration ordering and permits a valid headless Hub configuration to omit every JavaFX process.
|
||||
|
||||
## Impact
|
||||
|
||||
- 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 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.
|
||||
+17
@@ -0,0 +1,17 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Deferred JavaFX runtime features remain absent
|
||||
The JavaFX runtime service SHALL represent one JVM-wide toolkit and SHALL not implement multiple toolkits, headless emulation, toolkit replacement, shutdown, stop, restart, recovery, supervision, health monitoring, runtime status queries, window discovery or management, configuration, Context resolution, automatic dependency discovery/startup, lifecycle events, or subscriptions. Hub configuration MAY select the JavaFX runtime and applications only through explicit known process IDs in dependency-safe order; it SHALL not add configuration to the JavaFX service API. A valid headless Hub configuration MAY omit the runtime and every JavaFX application, in which case the Hub SHALL not construct or initialize the JavaFX runtime.
|
||||
|
||||
#### Scenario: Configured JavaFX consumers follow runtime startup
|
||||
- **WHEN** a valid Hub configuration selects JavaFX applications
|
||||
- **THEN** it lists `nenjim.javafx-runtime.service` before those applications and the shared runtime is started before they submit UI work
|
||||
|
||||
#### Scenario: Headless configuration omits JavaFX
|
||||
- **WHEN** a valid Hub configuration omits the JavaFX runtime and all JavaFX applications
|
||||
- **THEN** no JavaFX runtime or application process is constructed and the JavaFX toolkit remains uninitialized by Hub startup
|
||||
|
||||
#### Scenario: Runtime boundary is inspected
|
||||
- **WHEN** the delivered service, process implementation, Hub integration, and application constructors are examined
|
||||
- **THEN** only explicit one-time runtime startup, asynchronous task submission, configuration-ordered dependency injection, and optional omission are present
|
||||
|
||||
+83
@@ -0,0 +1,83 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Main is a thin outer bootstrap
|
||||
`com.r35157.nenjim.hubd.Main` SHALL be a final non-component class. Its `main(String[])` SHALL construct `com.r35157.nenjim.hubd.impl.ref.NenjimHubImpl` through a variable typed as `NenjimHub` and SHALL call `start()` exactly once. The Gradle application entry point SHALL continue to name this class. The bootstrap SHALL not select a configuration path or construct the Registry, manager, or business graph.
|
||||
|
||||
#### Scenario: Start through the outer bootstrap
|
||||
- **WHEN** the configured Java entry point is invoked
|
||||
- **THEN** `Main.main(...)` constructs one reference Hub through the public Hub interface and delegates startup to it exactly once
|
||||
|
||||
#### Scenario: No duplicate composition path remains
|
||||
- **WHEN** the source tree is inspected after migration
|
||||
- **THEN** the former Registry-manager and hardcoded autorun paths are absent, `Main` contains no composition path, and `NenjimHubImpl` is the sole owner of configuration-directed composition
|
||||
|
||||
#### Scenario: Bootstrap has no composition responsibility
|
||||
- **WHEN** the outer bootstrap source is inspected
|
||||
- **THEN** configuration parsing, composition, process tracking, online announcement, and the blocking wait are absent from `Main` and owned by the Hub implementation
|
||||
|
||||
### Requirement: Deferred runtime features remain absent
|
||||
The Registry SHALL represent one catalogue of already constructed components and SHALL not implement Contexts, artifact-version identity, resolution, classloading, automatic discovery, contributor APIs, public runtime loading or registration, removal, persistence, events, subscribers, automatic start-all, ownership tracking, usage counts, permissions, scopes, filtered views, or a common stop lifecycle. Hub autorun configuration SHALL remain a private startup input that selects only the implementation's known process constructors in explicit manual order. Except for that selection and the Process Manager's read-only polling of the existing started-process snapshot, the Hub SHALL not add lifecycle events, subscriptions, process controls, stop, restart, upgrade, health monitoring, recovery, automatic dependency construction, or context-bound dependency access.
|
||||
|
||||
#### Scenario: Consumer inspects the first Registry API
|
||||
- **WHEN** a consumer examines the public Registry, Registry-manager, process, Hub, and Process Manager contracts
|
||||
- **THEN** only read-only Registry lookup, passive registration, minimal process startup, Hub startup/snapshots, and the Process Manager role are available and configuration, discovery, resolution, and control remain absent from public APIs
|
||||
|
||||
### Requirement: NenjimHub owns composition and runtime startup
|
||||
`NenjimHub` SHALL remain the global runtime owner exposing only `start() throws Exception` plus an immutable ordered snapshot of successfully started process IDs. It SHALL be neither component nor process and SHALL not register itself. Its only accepted startup attempt SHALL validate the complete fixed-path Hub configuration before starting anything, construct and start Registry first, register Registry as `nenjim.registry.service`, record it, construct and register the complete passive graph, then lazily construct, register, start, and record only the remaining configured processes in exact order beginning with Journal. Registry and Journal managers SHALL remain distinct passive, unregistered handles retained privately by the Hub. Registration SHALL never imply startup. The Hub SHALL preserve the online point and blocking wait only after all configured processes succeed, without retry, rollback, dependency inference, or reordering.
|
||||
|
||||
#### Scenario: Registry starts before passive graph construction
|
||||
- **WHEN** the Hub has validated a complete startup plan and performs its first startup attempt
|
||||
- **THEN** it starts, registers, and records Registry first before constructing the passive component graph or any selected non-Registry process
|
||||
|
||||
#### Scenario: Journal follows passive composition but starts second
|
||||
- **WHEN** Registry bootstrap and passive graph construction have succeeded
|
||||
- **THEN** the Hub constructs, registers, starts, and records Journal before any later configured process, so Journal remains the second successful process
|
||||
|
||||
#### 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 configured Journal construction and registration have completed
|
||||
- **THEN** the same object is retrievable as both `JournalService` and `NenjimProcess` under `nenjim.journal.service`, while its manager is not registered
|
||||
|
||||
#### Scenario: Selected JavaFX runtime is process-discoverable
|
||||
- **WHEN** `nenjim.javafx-runtime.service` is selected and its registration has completed
|
||||
- **THEN** one object is retrievable as both `JavaFxRuntimeService` and `NenjimProcess` under that ID
|
||||
|
||||
#### Scenario: Selected JavaFX applications share the runtime
|
||||
- **WHEN** JavaFX runtime precedes selected Mission Control or Process Manager entries
|
||||
- **THEN** each selected application retains the same already-constructed `JavaFxRuntimeService` instance registered by the Hub
|
||||
|
||||
#### Scenario: Selected Process Manager is process-discoverable
|
||||
- **WHEN** `nenjim.process-manager.default` is selected after JavaFX runtime and its construction and registration complete
|
||||
- **THEN** the object constructed with the current Hub and shared JavaFX runtime is retrievable as both `NenjimProcessManager` and `NenjimProcess`
|
||||
|
||||
#### Scenario: Required passive bindings are registered
|
||||
- **WHEN** Hub passive composition completes
|
||||
- **THEN** all current passive component IDs and implementation choices from issue #76 are present exactly as configured, while process IDs other than Registry remain absent until selected
|
||||
|
||||
#### Scenario: Configured startup subset preserves order
|
||||
- **WHEN** Hub startup completes successfully
|
||||
- **THEN** successful process IDs exactly equal the validated `[AUTO_START]` entries in their declared order
|
||||
|
||||
#### Scenario: Omitted processes do not enter the Registry
|
||||
- **WHEN** a modern process ID is omitted from `[AUTO_START]`
|
||||
- **THEN** that process is neither constructed, registered, started, nor recorded even though its implementation is known to the Hub
|
||||
|
||||
#### Scenario: Journal failure is fail-fast
|
||||
- **WHEN** Journal construction, registration, or process startup throws
|
||||
- **THEN** Registry remains the only recorded process, no later configured process is constructed or started, the exception propagates, and the Hub neither announces online nor enters its final wait
|
||||
|
||||
#### Scenario: JavaFX runtime failure is fail-fast
|
||||
- **WHEN** selected JavaFX runtime construction, registration, or startup throws
|
||||
- **THEN** its ID is not recorded, no later configured process 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 passive composition, selected construction, registration, or process startup operation throws
|
||||
- **THEN** the exception propagates, no later process is constructed or started, the Hub neither announces online nor enters its final wait, and no generic rollback or retry is attempted
|
||||
|
||||
+138
@@ -0,0 +1,138 @@
|
||||
## Purpose
|
||||
|
||||
Defines the mandatory deployment configuration that selects which modern Nenjim processes the Hub constructs and starts, while preserving explicit order and fail-fast lifecycle semantics.
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Hub startup requires one fixed runtime configuration
|
||||
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 1 configuration
|
||||
- **THEN** the Hub derives its complete requested process order from that file before starting Registry
|
||||
|
||||
#### Scenario: Runtime configuration cannot be read
|
||||
- **WHEN** `conf/NenjimHub.conf` is missing, unreadable, or not a regular file
|
||||
- **THEN** startup fails with a diagnostic identifying `conf/NenjimHub.conf` before any process starts
|
||||
|
||||
#### Scenario: Only the example exists
|
||||
- **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 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 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=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
|
||||
- **WHEN** a comment-only line appears between two process IDs in `[AUTO_START]`
|
||||
- **THEN** both process IDs remain part of the ordered section
|
||||
|
||||
#### Scenario: Empty line terminates AUTO_START
|
||||
- **WHEN** a whitespace-only line appears after at least one `[AUTO_START]` entry
|
||||
- **THEN** the section terminates at that line and later actual content fails as unexpected content
|
||||
|
||||
#### Scenario: End of file terminates AUTO_START
|
||||
- **WHEN** the final process ID is immediately followed by end of file
|
||||
- **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 `1`
|
||||
- **THEN** configuration validation fails before any process starts and identifies the path, relevant line and reason
|
||||
|
||||
#### Scenario: Section structure is invalid
|
||||
- **WHEN** `[AUTO_START]` is absent, duplicated, misspelled, has a value or non-comment trailing token, follows another actual entry, or is replaced by an unknown section
|
||||
- **THEN** configuration validation fails before any process starts and identifies the path, relevant line, offending content and reason
|
||||
|
||||
### Requirement: The complete requested process plan is validated before startup
|
||||
Every active `[AUTO_START]` line SHALL be parsed through the canonical `NenjimComponentId` rules and retained in source order with its line location. Before Registry starts, validation SHALL reject invalid ID syntax, duplicate IDs, unknown IDs, passive-only component IDs, and IDs the reference Hub cannot construct as canonical `NenjimProcess` objects. The section SHALL contain Registry exactly once at position one and Journal exactly once at position two. Applicable failures SHALL identify `conf/NenjimHub.conf`, the relevant line, offending value, and reason.
|
||||
|
||||
#### Scenario: Process ID is malformed
|
||||
- **WHEN** an active section line is not a valid `NenjimComponentId`
|
||||
- **THEN** validation fails before Registry startup and identifies the path, line, offending value and component-ID reason
|
||||
|
||||
#### Scenario: Process ID is duplicated
|
||||
- **WHEN** the same canonical process ID appears more than once
|
||||
- **THEN** validation fails before Registry startup and identifies the duplicate value and line
|
||||
|
||||
#### Scenario: ID is not constructible as a process
|
||||
- **WHEN** an entry is unknown, identifies only a passive component, or is not in the Hub's modern process-construction catalogue
|
||||
- **THEN** validation fails before Registry startup rather than constructing or starting any process
|
||||
|
||||
#### Scenario: Bootstrap entries are not first and second
|
||||
- **WHEN** Registry is absent or not first, or Journal is absent or not second
|
||||
- **THEN** validation fails before Registry startup and identifies the required placement
|
||||
|
||||
### Requirement: Registry bootstraps eager passive composition
|
||||
After validating the entire plan, the Hub SHALL construct the configured Registry subsystem, start Registry, register its service and process object as `nenjim.registry.service`, and record that ID only after successful startup. The Hub SHALL then eagerly construct and register the complete current passive component graph needed by selectable processes. This passive phase SHALL not construct any canonical `NenjimProcess`, start background workers, initialize JavaFX, add startup IDs, infer process dependencies, or implicitly create an omitted process. Plain internal dependencies that are not `NenjimComponent` objects MAY be constructed as part of passive composition.
|
||||
|
||||
#### Scenario: Registry surrounds passive composition
|
||||
- **WHEN** a valid Hub startup begins
|
||||
- **THEN** Registry starts, is registered, and is recorded before the complete passive component graph is constructed and registered
|
||||
|
||||
#### Scenario: Passive composition completes
|
||||
- **WHEN** Registry bootstrap succeeds
|
||||
- **THEN** all current non-process building blocks, adapters, and services are constructed and registered without starting a process
|
||||
|
||||
#### Scenario: Passive construction fails
|
||||
- **WHEN** any passive component cannot be constructed or registered
|
||||
- **THEN** startup stops immediately with Registry remaining recorded and no configured process after Registry constructed or started
|
||||
|
||||
### Requirement: Selected processes are constructed and started lazily in exact order
|
||||
The Hub SHALL support the modern process IDs `nenjim.registry.service`, `nenjim.journal.service`, `assetaz.ticker.default`, `jupiter-perps-alarm.default`, `evelyn.service.prod`, `evelyn.service.test`, `evelyn.iou-burner.prod`, `nenjim.javafx-runtime.service`, `evelyn.mission-control.default`, and `nenjim.process-manager.default` through implementation-only construction capability that creates no process instance during validation. After passive composition, the Hub SHALL visit every configured entry after Registry in declared order, beginning with Journal. At each entry it SHALL construct only that process and any process-specific passive administration view, register the process under the exact configured ID, resolve it through the canonical `NenjimProcess` contract where applicable, call `start()`, and record the ID only after successful return.
|
||||
|
||||
The configuration SHALL be the complete manually ordered process dependency closure. The Hub SHALL not discover, insert, recursively construct, reorder, or automatically start dependencies. A process omitted from `[AUTO_START]` SHALL not be constructed, registered, started, or recorded, even when its implementation is available. Legacy process prototypes outside the modern Hub graph SHALL not be selectable.
|
||||
|
||||
#### Scenario: Configured process starts successfully
|
||||
- **WHEN** a configured process entry is reached and its dependencies are already available
|
||||
- **THEN** that process is constructed, registered, started, and recorded before the next entry is reached
|
||||
|
||||
#### Scenario: Process is omitted
|
||||
- **WHEN** a known process ID does not appear in `[AUTO_START]`
|
||||
- **THEN** no instance of that process is constructed or registered and its lifecycle is never started or recorded
|
||||
|
||||
#### Scenario: Jupiter Perps Alarm is selected
|
||||
- **WHEN** `jupiter-perps-alarm.default` is explicitly listed after its required predecessors
|
||||
- **THEN** the otherwise inactive modern alarm process is constructed, registered, started and recorded at that exact position
|
||||
|
||||
#### Scenario: Dependency order is invalid
|
||||
- **WHEN** a selected process is reached before a process dependency required by its current constructor or startup behavior
|
||||
- **THEN** construction or startup fails clearly without implicit dependency construction, repair, or reordering
|
||||
|
||||
#### Scenario: JavaFX processes are omitted
|
||||
- **WHEN** a valid headless plan omits `nenjim.javafx-runtime.service`, `evelyn.mission-control.default`, and `nenjim.process-manager.default`
|
||||
- **THEN** none of those objects is constructed or registered and the JavaFX toolkit remains uninitialized by the Hub
|
||||
|
||||
### Requirement: Configured startup is fail-fast and reports actual milestones
|
||||
Registry and every selected process SHALL be registered before its `start()` call and appended to the Hub's immutable ordered startup snapshot only after `start()` returns successfully. Construction failure SHALL leave the selected process unregistered. Registration or startup failure SHALL stop the plan before any later entry is constructed or started; a startup failure MAY leave that process registered but SHALL not record it. Earlier successful processes SHALL remain in snapshots, no rollback or retry SHALL occur, and the Hub SHALL announce its existing online point and enter its blocking runtime wait only after every configured process succeeds.
|
||||
|
||||
#### Scenario: Selected construction fails
|
||||
- **WHEN** construction of the current selected process throws
|
||||
- **THEN** the process is not registered or recorded, no later process is constructed, and the Hub does not announce online or enter its final wait
|
||||
|
||||
#### Scenario: Selected registration fails
|
||||
- **WHEN** registration of the constructed current process throws
|
||||
- **THEN** the process is not started or recorded, no later process is constructed, and no rollback is attempted
|
||||
|
||||
#### Scenario: Selected startup fails
|
||||
- **WHEN** the current process's `start()` throws
|
||||
- **THEN** it remains unrecorded, no later process is constructed or started, earlier successful IDs remain visible, and no rollback is attempted
|
||||
|
||||
#### Scenario: Configured startup completes
|
||||
- **WHEN** all configured process starts return successfully
|
||||
- **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 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 provides a generic minimal bootstrap
|
||||
- **WHEN** the example's uncommented process IDs are read in order
|
||||
- **THEN** they are only Registry and Journal, with no optional deployment-specific process ID present
|
||||
|
||||
#### Scenario: Operator uses the minimal headless example
|
||||
- **WHEN** the documented headless configuration is copied to the runtime path
|
||||
- **THEN** it selects only Registry and Journal and leaves every optional process for the operator to add explicitly
|
||||
@@ -0,0 +1,20 @@
|
||||
## 1. Hub configuration
|
||||
|
||||
- [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
|
||||
|
||||
- [x] 2.1 Split `NenjimHubImpl` composition so the complete passive dependency graph is constructed and registered only after successful Registry bootstrap and contains no canonical process instance.
|
||||
- [x] 2.2 Add an implementation-only lazy constructor catalogue for every supported modern non-Registry process, including optional Jupiter Perps Alarm, without encoding startup order.
|
||||
- [x] 2.3 Drive construction, registration, canonical process resolution, startup, and post-success recording from the validated configuration order while preserving fail-fast partial-startup behavior, online announcement, and final wait.
|
||||
|
||||
## 3. Configuration template and documentation
|
||||
|
||||
- [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
|
||||
|
||||
- [x] 4.1 Inspect the implementation to confirm no runtime reference to the example file, no fixed autorun sequence, no eager process construction, and no public API expansion remains.
|
||||
- [x] 4.2 Run strict OpenSpec validation and the complete Gradle build, resolving all failures without running the production Hub or adding general automated tests.
|
||||
@@ -72,9 +72,16 @@ The implementation's `start()` SHALL be the only operation that calls `Platform.
|
||||
- **THEN** `com.r35157.libs.javafx.JavaFxRuntime` is absent and only `JavaFxRuntimeServiceImpl.start()` calls `Platform.startup(...)`
|
||||
|
||||
### Requirement: Deferred JavaFX runtime features remain absent
|
||||
The JavaFX runtime service SHALL represent one JVM-wide toolkit and SHALL not implement multiple toolkits, headless emulation, toolkit replacement, shutdown, stop, restart, recovery, supervision, health monitoring, runtime status queries, window discovery or management, configuration, Context resolution, automatic dependency discovery/startup, lifecycle events, or subscriptions. This change SHALL not add `NenjimHub.conf` or configurable autorun.
|
||||
The JavaFX runtime service SHALL represent one JVM-wide toolkit and SHALL not implement multiple toolkits, headless emulation, toolkit replacement, shutdown, stop, restart, recovery, supervision, health monitoring, runtime status queries, window discovery or management, configuration, Context resolution, automatic dependency discovery/startup, lifecycle events, or subscriptions. Hub configuration MAY select the JavaFX runtime and applications only through explicit known process IDs in dependency-safe order; it SHALL not add configuration to the JavaFX service API. A valid headless Hub configuration MAY omit the runtime and every JavaFX application, in which case the Hub SHALL not construct or initialize the JavaFX runtime.
|
||||
|
||||
#### Scenario: Configured JavaFX consumers follow runtime startup
|
||||
- **WHEN** a valid Hub configuration selects JavaFX applications
|
||||
- **THEN** it lists `nenjim.javafx-runtime.service` before those applications and the shared runtime is started before they submit UI work
|
||||
|
||||
#### Scenario: Headless configuration omits JavaFX
|
||||
- **WHEN** a valid Hub configuration omits the JavaFX runtime and all JavaFX applications
|
||||
- **THEN** no JavaFX runtime or application process is constructed and the JavaFX toolkit remains uninitialized by Hub startup
|
||||
|
||||
#### Scenario: Runtime boundary is inspected
|
||||
- **WHEN** the delivered service, process implementation, Hub integration, and application constructors are examined
|
||||
- **THEN** only explicit one-time startup, asynchronous task submission, fixed Hub ordering, and dependency injection are present
|
||||
|
||||
- **THEN** only explicit one-time runtime startup, asynchronous task submission, configuration-ordered dependency injection, and optional omission are present
|
||||
|
||||
@@ -108,7 +108,7 @@ A non-bootstrap application or service that owns a component choice SHALL receiv
|
||||
- **THEN** it receives only `NenjimRegistryService` and cannot self-register
|
||||
|
||||
### Requirement: Main is a thin outer bootstrap
|
||||
`com.r35157.nenjim.hubd.Main` SHALL be a final non-component class. Its `main(String[])` SHALL construct `com.r35157.nenjim.hubd.impl.ref.NenjimHubImpl` through a variable typed as `NenjimHub` and SHALL call `start()` exactly once. The Gradle application entry point SHALL continue to name this class. The bootstrap SHALL not construct the Registry, manager, or business graph.
|
||||
`com.r35157.nenjim.hubd.Main` SHALL be a final non-component class. Its `main(String[])` SHALL construct `com.r35157.nenjim.hubd.impl.ref.NenjimHubImpl` through a variable typed as `NenjimHub` and SHALL call `start()` exactly once. The Gradle application entry point SHALL continue to name this class. The bootstrap SHALL not select a configuration path or construct the Registry, manager, or business graph.
|
||||
|
||||
#### Scenario: Start through the outer bootstrap
|
||||
- **WHEN** the configured Java entry point is invoked
|
||||
@@ -116,11 +116,11 @@ A non-bootstrap application or service that owns a component choice SHALL receiv
|
||||
|
||||
#### Scenario: No duplicate composition path remains
|
||||
- **WHEN** the source tree is inspected after migration
|
||||
- **THEN** the former Registry-manager composition path is absent, `Main` contains no composition path, and `NenjimHubImpl` is the sole owner of the current hardcoded component graph
|
||||
- **THEN** the former Registry-manager and hardcoded autorun paths are absent, `Main` contains no composition path, and `NenjimHubImpl` is the sole owner of configuration-directed composition
|
||||
|
||||
#### Scenario: Bootstrap has no composition responsibility
|
||||
- **WHEN** the outer bootstrap source is inspected
|
||||
- **THEN** composition, process tracking, online announcement, and the blocking wait are absent from `Main` and owned by the Hub implementation
|
||||
- **THEN** configuration parsing, composition, process tracking, online announcement, and the blocking wait are absent from `Main` and owned by the Hub implementation
|
||||
|
||||
### Requirement: Registry terminology and package boundaries are consistent
|
||||
Public component contracts SHALL live in `com.r35157.nenjim.component`; the canonical process contract SHALL live in `com.r35157.nenjim.process`; the global Hub contract SHALL live in `com.r35157.nenjim.hubd`; public Registry service contracts SHALL live in `com.r35157.nenjim.service.registry`; and the component ID SHALL live in its `.valuetypes` package. Registry storage and its package-private administration view SHALL live in `.impl.ref`, where an implementation-only construction boundary MAY also live without exposing administration. Directly affected Ticker price-source API and implementation packages SHALL continue to use `.pricesource`. Public reference-type parameters, return values, and record components added or changed by this capability SHALL declare explicit nullability.
|
||||
@@ -138,11 +138,11 @@ Public component contracts SHALL live in `com.r35157.nenjim.component`; the cano
|
||||
- **THEN** exactly one canonical `com.r35157.nenjim.process.NenjimProcess` contract exists and no `NenjimApplication` type remains
|
||||
|
||||
### Requirement: Deferred runtime features remain absent
|
||||
The Registry SHALL represent one catalogue of already constructed components and SHALL not implement Contexts, artifact-version identity, resolution, classloading, automatic discovery, contributor APIs, public runtime loading or registration, removal, persistence, events, subscribers, user configuration, automatic selection, automatic start-all, ownership tracking, usage counts, permissions, scopes, filtered views, or a common stop lifecycle. Except for the Process Manager's read-only polling of the existing started-process snapshot, the Hub SHALL not add configurable autorun, lifecycle events, subscriptions, process controls, stop, restart, upgrade, health monitoring, recovery, or context-bound dependency access.
|
||||
The Registry SHALL represent one catalogue of already constructed components and SHALL not implement Contexts, artifact-version identity, resolution, classloading, automatic discovery, contributor APIs, public runtime loading or registration, removal, persistence, events, subscribers, automatic start-all, ownership tracking, usage counts, permissions, scopes, filtered views, or a common stop lifecycle. Hub autorun configuration SHALL remain a private startup input that selects only the implementation's known process constructors in explicit manual order. Except for that selection and the Process Manager's read-only polling of the existing started-process snapshot, the Hub SHALL not add lifecycle events, subscriptions, process controls, stop, restart, upgrade, health monitoring, recovery, automatic dependency construction, or context-bound dependency access.
|
||||
|
||||
#### Scenario: Consumer inspects the first Registry API
|
||||
- **WHEN** a consumer examines the public Registry, Registry-manager, process, Hub, and Process Manager contracts
|
||||
- **THEN** only read-only Registry lookup, passive registration, minimal process startup, Hub startup/snapshots, and the Process Manager role are available and no deferred runtime feature is exposed
|
||||
- **THEN** only read-only Registry lookup, passive registration, minimal process startup, Hub startup/snapshots, and the Process Manager role are available and configuration, discovery, resolution, and control remain absent from public APIs
|
||||
|
||||
### Requirement: Components and processes have minimal orthogonal contracts
|
||||
`NenjimComponent` SHALL remain a pure marker with no component-ID or lifecycle property. The one canonical `com.r35157.nenjim.process.NenjimProcess` SHALL extend `NenjimComponent` and SHALL expose only `start() throws Exception` as its common lifecycle operation. Service and application SHALL remain independent domain or orchestration roles: an implementation in either role SHALL additionally implement `NenjimProcess` only when it has a Hub-managed active startup lifecycle. Passive components SHALL not implement `NenjimProcess`, and no `NenjimApplication` compatibility type SHALL remain.
|
||||
@@ -186,63 +186,63 @@ 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 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. During application composition the Hub SHALL construct exactly one `JavaFxRuntimeServiceImpl`, register it as `nenjim.javafx-runtime.service`, inject its service view into Mission Control and Process Manager, construct the Process Manager with itself, and register that manager as `nenjim.process-manager.default`. The Hub SHALL resolve only explicitly enabled IDs through `NenjimProcess`, start the JavaFX runtime service after enabled non-JavaFX business processes and before Mission Control and Process Manager, start Process Manager last, announce the existing online point, and preserve the existing blocking wait. Registration SHALL never imply startup, and the Registry and Journal managers SHALL remain distinct passive, unregistered handles retained privately by the Hub.
|
||||
`NenjimHub` SHALL remain the global runtime owner exposing only `start() throws Exception` plus an immutable ordered snapshot of successfully started process IDs. It SHALL be neither component nor process and SHALL not register itself. Its only accepted startup attempt SHALL validate the complete fixed-path Hub configuration before starting anything, construct and start Registry first, register Registry as `nenjim.registry.service`, record it, construct and register the complete passive graph, then lazily construct, register, start, and record only the remaining configured processes in exact order beginning with Journal. Registry and Journal managers SHALL remain distinct passive, unregistered handles retained privately by the Hub. Registration SHALL never imply startup. The Hub SHALL preserve the online point and blocking wait only after all configured processes succeed, without retry, rollback, dependency inference, or reordering.
|
||||
|
||||
#### 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: Registry starts before passive graph construction
|
||||
- **WHEN** the Hub has validated a complete startup plan and performs its first startup attempt
|
||||
- **THEN** it starts, registers, and records Registry first before constructing the passive component graph or any selected non-Registry process
|
||||
|
||||
#### 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: Journal follows passive composition but starts second
|
||||
- **WHEN** Registry bootstrap and passive graph construction have succeeded
|
||||
- **THEN** the Hub constructs, registers, starts, and records Journal before any later configured process, so Journal remains the second successful process
|
||||
|
||||
#### 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
|
||||
- **WHEN** the configured Journal construction and registration have completed
|
||||
- **THEN** the same object is retrievable as both `JournalService` and `NenjimProcess` under `nenjim.journal.service`, while its manager is not registered
|
||||
|
||||
#### Scenario: JavaFX runtime is process-discoverable
|
||||
- **WHEN** Hub-owned application composition has completed
|
||||
- **THEN** one object is retrievable as both `JavaFxRuntimeService` and `NenjimProcess` under `nenjim.javafx-runtime.service`
|
||||
#### Scenario: Selected JavaFX runtime is process-discoverable
|
||||
- **WHEN** `nenjim.javafx-runtime.service` is selected and its registration has completed
|
||||
- **THEN** one object is retrievable as both `JavaFxRuntimeService` and `NenjimProcess` under that ID
|
||||
|
||||
#### Scenario: JavaFX applications share the runtime
|
||||
- **WHEN** Hub-owned application composition has completed
|
||||
- **THEN** Mission Control and Process Manager retain the same `JavaFxRuntimeService` instance registered by the Hub
|
||||
#### Scenario: Selected JavaFX applications share the runtime
|
||||
- **WHEN** JavaFX runtime precedes selected Mission Control or Process Manager entries
|
||||
- **THEN** each selected application retains the same already-constructed `JavaFxRuntimeService` instance registered by the Hub
|
||||
|
||||
#### Scenario: Process Manager is process-discoverable
|
||||
- **WHEN** Hub-owned application composition has completed
|
||||
- **THEN** the object constructed with the current Hub and shared JavaFX runtime is retrievable as both `NenjimProcessManager` and `NenjimProcess` under `nenjim.process-manager.default`
|
||||
#### Scenario: Selected Process Manager is process-discoverable
|
||||
- **WHEN** `nenjim.process-manager.default` is selected after JavaFX runtime and its construction and registration complete
|
||||
- **THEN** the object constructed with the current Hub and shared JavaFX runtime is retrievable as both `NenjimProcessManager` and `NenjimProcess`
|
||||
|
||||
#### Scenario: Required hardcoded bindings are registered
|
||||
- **WHEN** Hub composition completes
|
||||
- **THEN** Journal, the JavaFX runtime, the Process Manager, 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: Required passive bindings are registered
|
||||
- **WHEN** Hub passive composition completes
|
||||
- **THEN** all current passive component IDs and implementation choices from issue #76 are present exactly as configured, while process IDs other than Registry remain absent until selected
|
||||
|
||||
#### Scenario: Explicit startup subset preserves order
|
||||
- **WHEN** Hub startup succeeds through the Process Manager 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`, `nenjim.javafx-runtime.service`, `evelyn.mission-control.default`, and `nenjim.process-manager.default`
|
||||
#### Scenario: Configured startup subset preserves order
|
||||
- **WHEN** Hub startup completes successfully
|
||||
- **THEN** successful process IDs exactly equal the validated `[AUTO_START]` entries in their declared order
|
||||
|
||||
#### Scenario: Deliberately inactive processes remain inactive
|
||||
- **WHEN** Hub startup reaches its online point
|
||||
- **THEN** `jupiter-perps-alarm.default` and the dormant Composer, Test Tool, Soda Task Manager, and Suwimo Client paths have not been started
|
||||
#### Scenario: Omitted processes do not enter the Registry
|
||||
- **WHEN** a modern process ID is omitted from `[AUTO_START]`
|
||||
- **THEN** that process is neither constructed, registered, started, nor recorded even though its implementation is known to the Hub
|
||||
|
||||
#### 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
|
||||
- **WHEN** Journal construction, registration, or process startup throws
|
||||
- **THEN** Registry remains the only recorded process, no later configured process is constructed or started, the exception propagates, and the Hub neither announces online nor enters its final wait
|
||||
|
||||
#### Scenario: JavaFX runtime failure is fail-fast
|
||||
- **WHEN** JavaFX runtime service startup throws
|
||||
- **THEN** its ID is not recorded, Mission Control and Process Manager do not start, the exception propagates, and the Hub neither announces online nor enters its final wait
|
||||
- **WHEN** selected JavaFX runtime construction, registration, or startup throws
|
||||
- **THEN** its ID is not recorded, no later configured process 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
|
||||
- **WHEN** any passive composition, selected construction, registration, or process startup operation throws
|
||||
- **THEN** the exception propagates, no later process is constructed or started, 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
|
||||
`NenjimHub.getStartedProcessIds()` SHALL be safe before, during, and after startup and SHALL return an immutable point-in-time snapshot in successful startup order. A process ID SHALL be appended only after that process's `start()` call returns successfully, including `nenjim.javafx-runtime.service` and `nenjim.process-manager.default`. Earlier successful entries SHALL remain visible after a later failure, while a failing process SHALL never be included. The snapshot SHALL make no health or continued-liveness guarantee.
|
||||
|
||||
@@ -0,0 +1,140 @@
|
||||
# nenjim-hub-configuration Specification
|
||||
|
||||
## Purpose
|
||||
|
||||
Defines the mandatory deployment configuration that selects which modern Nenjim processes the Hub constructs and starts, while preserving explicit order and fail-fast lifecycle semantics.
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: Hub startup requires one fixed runtime configuration
|
||||
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 1 configuration
|
||||
- **THEN** the Hub derives its complete requested process order from that file before starting Registry
|
||||
|
||||
#### Scenario: Runtime configuration cannot be read
|
||||
- **WHEN** `conf/NenjimHub.conf` is missing, unreadable, or not a regular file
|
||||
- **THEN** startup fails with a diagnostic identifying `conf/NenjimHub.conf` before any process starts
|
||||
|
||||
#### Scenario: Only the example exists
|
||||
- **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 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 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=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
|
||||
- **WHEN** a comment-only line appears between two process IDs in `[AUTO_START]`
|
||||
- **THEN** both process IDs remain part of the ordered section
|
||||
|
||||
#### Scenario: Empty line terminates AUTO_START
|
||||
- **WHEN** a whitespace-only line appears after at least one `[AUTO_START]` entry
|
||||
- **THEN** the section terminates at that line and later actual content fails as unexpected content
|
||||
|
||||
#### Scenario: End of file terminates AUTO_START
|
||||
- **WHEN** the final process ID is immediately followed by end of file
|
||||
- **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 `1`
|
||||
- **THEN** configuration validation fails before any process starts and identifies the path, relevant line and reason
|
||||
|
||||
#### Scenario: Section structure is invalid
|
||||
- **WHEN** `[AUTO_START]` is absent, duplicated, misspelled, has a value or non-comment trailing token, follows another actual entry, or is replaced by an unknown section
|
||||
- **THEN** configuration validation fails before any process starts and identifies the path, relevant line, offending content and reason
|
||||
|
||||
### Requirement: The complete requested process plan is validated before startup
|
||||
Every active `[AUTO_START]` line SHALL be parsed through the canonical `NenjimComponentId` rules and retained in source order with its line location. Before Registry starts, validation SHALL reject invalid ID syntax, duplicate IDs, unknown IDs, passive-only component IDs, and IDs the reference Hub cannot construct as canonical `NenjimProcess` objects. The section SHALL contain Registry exactly once at position one and Journal exactly once at position two. Applicable failures SHALL identify `conf/NenjimHub.conf`, the relevant line, offending value, and reason.
|
||||
|
||||
#### Scenario: Process ID is malformed
|
||||
- **WHEN** an active section line is not a valid `NenjimComponentId`
|
||||
- **THEN** validation fails before Registry startup and identifies the path, line, offending value and component-ID reason
|
||||
|
||||
#### Scenario: Process ID is duplicated
|
||||
- **WHEN** the same canonical process ID appears more than once
|
||||
- **THEN** validation fails before Registry startup and identifies the duplicate value and line
|
||||
|
||||
#### Scenario: ID is not constructible as a process
|
||||
- **WHEN** an entry is unknown, identifies only a passive component, or is not in the Hub's modern process-construction catalogue
|
||||
- **THEN** validation fails before Registry startup rather than constructing or starting any process
|
||||
|
||||
#### Scenario: Bootstrap entries are not first and second
|
||||
- **WHEN** Registry is absent or not first, or Journal is absent or not second
|
||||
- **THEN** validation fails before Registry startup and identifies the required placement
|
||||
|
||||
### Requirement: Registry bootstraps eager passive composition
|
||||
After validating the entire plan, the Hub SHALL construct the configured Registry subsystem, start Registry, register its service and process object as `nenjim.registry.service`, and record that ID only after successful startup. The Hub SHALL then eagerly construct and register the complete current passive component graph needed by selectable processes. This passive phase SHALL not construct any canonical `NenjimProcess`, start background workers, initialize JavaFX, add startup IDs, infer process dependencies, or implicitly create an omitted process. Plain internal dependencies that are not `NenjimComponent` objects MAY be constructed as part of passive composition.
|
||||
|
||||
#### Scenario: Registry surrounds passive composition
|
||||
- **WHEN** a valid Hub startup begins
|
||||
- **THEN** Registry starts, is registered, and is recorded before the complete passive component graph is constructed and registered
|
||||
|
||||
#### Scenario: Passive composition completes
|
||||
- **WHEN** Registry bootstrap succeeds
|
||||
- **THEN** all current non-process building blocks, adapters, and services are constructed and registered without starting a process
|
||||
|
||||
#### Scenario: Passive construction fails
|
||||
- **WHEN** any passive component cannot be constructed or registered
|
||||
- **THEN** startup stops immediately with Registry remaining recorded and no configured process after Registry constructed or started
|
||||
|
||||
### Requirement: Selected processes are constructed and started lazily in exact order
|
||||
The Hub SHALL support the modern process IDs `nenjim.registry.service`, `nenjim.journal.service`, `assetaz.ticker.default`, `jupiter-perps-alarm.default`, `evelyn.service.prod`, `evelyn.service.test`, `evelyn.iou-burner.prod`, `nenjim.javafx-runtime.service`, `evelyn.mission-control.default`, and `nenjim.process-manager.default` through implementation-only construction capability that creates no process instance during validation. After passive composition, the Hub SHALL visit every configured entry after Registry in declared order, beginning with Journal. At each entry it SHALL construct only that process and any process-specific passive administration view, register the process under the exact configured ID, resolve it through the canonical `NenjimProcess` contract where applicable, call `start()`, and record the ID only after successful return.
|
||||
|
||||
The configuration SHALL be the complete manually ordered process dependency closure. The Hub SHALL not discover, insert, recursively construct, reorder, or automatically start dependencies. A process omitted from `[AUTO_START]` SHALL not be constructed, registered, started, or recorded, even when its implementation is available. Legacy process prototypes outside the modern Hub graph SHALL not be selectable.
|
||||
|
||||
#### Scenario: Configured process starts successfully
|
||||
- **WHEN** a configured process entry is reached and its dependencies are already available
|
||||
- **THEN** that process is constructed, registered, started, and recorded before the next entry is reached
|
||||
|
||||
#### Scenario: Process is omitted
|
||||
- **WHEN** a known process ID does not appear in `[AUTO_START]`
|
||||
- **THEN** no instance of that process is constructed or registered and its lifecycle is never started or recorded
|
||||
|
||||
#### Scenario: Jupiter Perps Alarm is selected
|
||||
- **WHEN** `jupiter-perps-alarm.default` is explicitly listed after its required predecessors
|
||||
- **THEN** the otherwise inactive modern alarm process is constructed, registered, started and recorded at that exact position
|
||||
|
||||
#### Scenario: Dependency order is invalid
|
||||
- **WHEN** a selected process is reached before a process dependency required by its current constructor or startup behavior
|
||||
- **THEN** construction or startup fails clearly without implicit dependency construction, repair, or reordering
|
||||
|
||||
#### Scenario: JavaFX processes are omitted
|
||||
- **WHEN** a valid headless plan omits `nenjim.javafx-runtime.service`, `evelyn.mission-control.default`, and `nenjim.process-manager.default`
|
||||
- **THEN** none of those objects is constructed or registered and the JavaFX toolkit remains uninitialized by the Hub
|
||||
|
||||
### Requirement: Configured startup is fail-fast and reports actual milestones
|
||||
Registry and every selected process SHALL be registered before its `start()` call and appended to the Hub's immutable ordered startup snapshot only after `start()` returns successfully. Construction failure SHALL leave the selected process unregistered. Registration or startup failure SHALL stop the plan before any later entry is constructed or started; a startup failure MAY leave that process registered but SHALL not record it. Earlier successful processes SHALL remain in snapshots, no rollback or retry SHALL occur, and the Hub SHALL announce its existing online point and enter its blocking runtime wait only after every configured process succeeds.
|
||||
|
||||
#### Scenario: Selected construction fails
|
||||
- **WHEN** construction of the current selected process throws
|
||||
- **THEN** the process is not registered or recorded, no later process is constructed, and the Hub does not announce online or enter its final wait
|
||||
|
||||
#### Scenario: Selected registration fails
|
||||
- **WHEN** registration of the constructed current process throws
|
||||
- **THEN** the process is not started or recorded, no later process is constructed, and no rollback is attempted
|
||||
|
||||
#### Scenario: Selected startup fails
|
||||
- **WHEN** the current process's `start()` throws
|
||||
- **THEN** it remains unrecorded, no later process is constructed or started, earlier successful IDs remain visible, and no rollback is attempted
|
||||
|
||||
#### Scenario: Configured startup completes
|
||||
- **WHEN** all configured process starts return successfully
|
||||
- **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 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 provides a generic minimal bootstrap
|
||||
- **WHEN** the example's uncommented process IDs are read in order
|
||||
- **THEN** they are only Registry and Journal, with no optional deployment-specific process ID present
|
||||
|
||||
#### Scenario: Operator uses the minimal headless example
|
||||
- **WHEN** the documented headless configuration is copied to the runtime path
|
||||
- **THEN** it selects only Registry and Journal and leaves every optional process for the operator to add explicitly
|
||||
Reference in New Issue
Block a user