# 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