# nenjim-component-registry Specification

## Purpose

Provide one typed, read-only catalogue of constructed Nenjim components and a lifecycle manager that owns the current hardcoded composition without introducing Context or dynamic-loading semantics.
## Requirements
### Requirement: Component IDs are canonical validated values
`NenjimComponentId` SHALL reject null, strip surrounding Unicode whitespace before storage and validation, and accept only lower-case ASCII dot-separated segments whose first character is a letter and whose remaining subparts contain lower-case letters or digits separated by single internal hyphens. Standard record value equality and hashing SHALL define ID equality.

#### Scenario: Surrounding whitespace is canonicalized
- **WHEN** an ID is constructed from `   nenjim.registry.service   `
- **THEN** its stored value is `nenjim.registry.service`

#### Scenario: Valid component IDs are accepted
- **WHEN** IDs such as `nenjim.registry.service`, `assetaz.price-source.raydium-pool`, or `evelyn.service.prod` are constructed
- **THEN** construction succeeds

#### Scenario: Invalid component IDs are rejected
- **WHEN** an ID is null or contains uppercase letters, underscores, internal whitespace, an empty segment, a leading or trailing dot, or a malformed hyphen
- **THEN** construction fails with the specified null or argument exception category and identifies the invalid canonicalized value without exposing secrets

### Requirement: Registry consumers receive only typed read-only lookup
`NenjimRegistryService` SHALL be a Nenjim component and SHALL expose exactly an ordered-ID lookup by component interface and a nullable typed lookup by component ID and expected component interface. Both operations SHALL reject null arguments. A query type SHALL be an interface extending `NenjimComponent`; concrete classes and ordinary interfaces SHALL be rejected.

#### Scenario: List matching component IDs
- **WHEN** a caller requests the IDs for a valid component interface
- **THEN** the Registry returns all registrations indexed under that interface in registration order as an immutable snapshot that is not changed by later registrations

#### Scenario: No component implements an interface
- **WHEN** a valid component interface has no indexed registration
- **THEN** the Registry returns an empty immutable list rather than null

#### Scenario: Retrieve a matching component
- **WHEN** an existing component ID is requested through an interface implemented by its object
- **THEN** the Registry returns that object cast to the requested interface

#### Scenario: Component ID is missing
- **WHEN** an unused component ID is requested through a valid component interface
- **THEN** the Registry returns null

#### Scenario: Existing component has the wrong type
- **WHEN** an existing component ID is requested through a component interface its object does not implement
- **THEN** lookup fails with `IllegalArgumentException` identifying the ID, requested interface name, and actual implementation class name

#### Scenario: Query token is not a component interface
- **WHEN** a caller supplies a concrete class, an ordinary interface, or null as a query token
- **THEN** the Registry rejects it with the specified argument or null exception category

#### Scenario: Consumer cannot administer registrations
- **WHEN** ordinary code receives `NenjimRegistryService`
- **THEN** that public view exposes no registration, removal, loading, resolver, class-loading, stop, permission, event, or persistence operation

### Requirement: Internal registration maintains an interface index
The internal Registry administration view SHALL remain package-private, SHALL not be a Nenjim component, and SHALL expose registration but no removal. Each registration SHALL atomically add a unique ID to a primary ID-to-object catalogue and to a secondary ordered index under every implemented interface in the recursive hierarchy that extends `NenjimComponent`. It SHALL not index concrete classes, ordinary interfaces, or the administration interface. Reads and registrations SHALL remain internally consistent when registrations occur after startup.

#### Scenario: Duplicate ID is rejected
- **WHEN** a component is registered under an ID already present in the Registry
- **THEN** registration fails with `IllegalArgumentException` identifying the duplicated ID and both the existing and attempted implementation class names without changing either index

#### Scenario: Null registration input is rejected
- **WHEN** a registration supplies a null ID or component
- **THEN** registration fails with `NullPointerException` without changing either index

#### Scenario: Same instance receives aliases
- **WHEN** the same object is registered under multiple different unused IDs
- **THEN** every registration succeeds and each ID resolves to the identical object reference

#### Scenario: Inherited component interfaces are indexed
- **WHEN** a registered object implements a component interface that extends another component interface
- **THEN** the registration ID appears under both interfaces, including inherited interfaces not directly declared by the implementation class

#### Scenario: One registration exposes multiple views
- **WHEN** one object implements multiple component interfaces and is registered once
- **THEN** its one ID appears under every implemented component interface and typed lookups preserve reference identity

#### Scenario: Registration occurs after startup
- **WHEN** internal administration registers another component after the Registry has started
- **THEN** subsequent queries observe a consistent registration while previously returned ID snapshots remain unchanged

### Requirement: Registry startup is single-use and gates queries
The Registry process's first `start()` call SHALL be the only accepted attempt and SHALL enable queries only after successful startup. A later attempt SHALL fail with `IllegalStateException`, including when the first attempt failed. Registration SHALL remain allowed before and after startup, and starting the Registry SHALL not construct, register, start, or stop another component.

#### Scenario: Query before startup
- **WHEN** either lookup operation is called before successful Registry startup
- **THEN** it fails with `IllegalStateException`

#### Scenario: Registry starts once
- **WHEN** the Registry is started successfully and start is requested again
- **THEN** the second request fails with `IllegalStateException`

#### Scenario: Failed start is not retried
- **WHEN** the first Registry start attempt fails
- **THEN** every later start request fails with `IllegalStateException`

### Requirement: Applications own explicit dependency selection
A non-bootstrap application or service that owns a component choice SHALL receive the public Registry view through constructor injection, express the choice as one or more explicit component IDs, and use typed lookup. A required missing or wrong-type binding SHALL fail clearly rather than selecting the first component returned for an interface. The initial Ticker composition SHALL explicitly select only `assetaz.price-source.raydium-pool.eve-usdt`; `assetaz.price-source.hardcoded` SHALL remain registered but inactive.

#### Scenario: Ticker resolves its configured source
- **WHEN** the Ticker is constructed with the public Registry and the Raydium EVE/USDT source ID
- **THEN** it resolves that exact `PriceSource` and does not activate the hardcoded source

#### Scenario: Required configured dependency is missing
- **WHEN** an application resolves a required hardcoded component ID that is absent
- **THEN** construction or startup fails with a diagnostic identifying the required ID and interface without exposing component secrets

#### Scenario: Internal administration is not injected
- **WHEN** an ordinary application receives its Registry dependency
- **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.

#### 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 composition path is absent, `Main` contains no composition path, and `NenjimHubImpl` is the sole owner of the current hardcoded component graph

#### 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

### 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.

#### Scenario: Ticker source packages are inspected
- **WHEN** source packages and imports are searched after migration
- **THEN** no directly affected Ticker price-source package uses the `plugins` segment

#### Scenario: Internal Registry administration is inspected
- **WHEN** an ordinary consumer compiles against the public Registry packages
- **THEN** the package-private administration interface and Registry implementation are inaccessible, and the public service exposes no path to its active manager

#### Scenario: Canonical process API is inspected
- **WHEN** modern source packages are searched after migration
- **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. The Hub SHALL not add configurable autorun, process-manager integration, stop, restart, upgrade, health monitoring, recovery, or context-bound dependency access.

#### Scenario: Consumer inspects the first Registry API
- **WHEN** a consumer examines the public Registry, Registry-manager, process, and Hub contracts
- **THEN** only read-only Registry lookup, passive registration, minimal process startup, and Hub startup/snapshot operations are available and no deferred feature is exposed

### 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.

#### Scenario: One object has more than one registration identity
- **WHEN** the same component object is registered under two different unused component IDs
- **THEN** both IDs identify the same object because IDs are Registry metadata rather than object properties

#### Scenario: A service implementation is startable
- **WHEN** a service implementation has a no-argument active startup lifecycle managed by the Hub
- **THEN** the implementation is discoverable as `NenjimProcess` without adding lifecycle operations solely to its domain service interface

#### Scenario: Application role and process lifecycle are independent
- **WHEN** a component performs a user-facing or orchestration application role
- **THEN** that role alone neither makes it a process nor changes its domain interfaces

#### Scenario: Common stop is unavailable
- **WHEN** a caller uses `NenjimProcess`
- **THEN** the contract exposes no stop, restart, health, context, or dependency-lookup operation

### Requirement: Registry construction preserves the administrative boundary
The reference Registry construction boundary SHALL create one Registry object exposed through both `NenjimRegistryService` and `NenjimProcess`, plus one distinct `NenjimRegistryServiceManager` bound to that Registry. The service and process views SHALL preserve object identity. The construction helper SHALL own no lifecycle, SHALL be neither a component nor a process, SHALL not be Registry-discoverable, and SHALL expose neither the package-private administration interface nor a way to derive the active Registry's manager from an ordinary service reference.

#### Scenario: Registry views preserve identity
- **WHEN** the Hub obtains a newly constructed Registry assembly
- **THEN** its service and process views reference the identical Registry object while its manager is a different object

#### Scenario: Ordinary service reference remains read-only
- **WHEN** an ordinary consumer receives the public Registry service view
- **THEN** the consumer cannot name or derive the package-private administration view or obtain the manager bound to that active Registry

### Requirement: Registry manager is a passive registration handle
`NenjimRegistryServiceManager` SHALL expose exactly registration by component ID and component. It SHALL be neither a Nenjim component nor a Nenjim process, SHALL remain privately retained by the Hub, and SHALL delegate registration to the Registry's internal administration view while preserving duplicate-ID, interface-indexing, and post-start registration behavior. It SHALL not construct the business graph, own lifecycle, start or stop any process, expose the Registry service, or be registered under `nenjim.registry.service-manager` or any other component ID.

#### Scenario: Hub registers a component
- **WHEN** the Hub passes an unused component ID and a non-null component to the manager
- **THEN** the component becomes available through the Registry's existing typed interface index without being activated

#### Scenario: Registry manager is not discoverable
- **WHEN** Registry registrations are inspected after Hub composition
- **THEN** no component ID identifies the manager and no lookup returns it as a component or process

### Requirement: NenjimHub owns composition and runtime startup
`NenjimHub` SHALL be the global runtime owner and SHALL expose `start() throws Exception` plus an immutable ordered snapshot of successfully started process IDs. It SHALL be neither a component nor a process and SHALL not register itself. Its only accepted startup attempt SHALL construct the Registry subsystem, start the Registry process first, register it as `nenjim.registry.service`, construct and register the complete hardcoded component set from issue #76 in dependency order, resolve only the explicitly enabled IDs through `NenjimProcess`, start them in dependency-safe order, announce the existing online point, and preserve the existing blocking wait. Registration SHALL never imply startup.

#### Scenario: Registry starts before graph construction
- **WHEN** the Hub performs its first startup attempt
- **THEN** it starts the Registry, registers it as `nenjim.registry.service`, and records that ID before constructing components whose constructors may query the Registry

#### Scenario: Registry is process-discoverable
- **WHEN** the Registry registration has completed
- **THEN** the same object is retrievable as both `NenjimRegistryService` and `NenjimProcess`

#### Scenario: Required hardcoded bindings are registered
- **WHEN** Hub composition completes
- **THEN** all component IDs and implementation choices enumerated by issue #76 are present exactly as configured, including intentionally inactive components and excluding the former Registry-manager ID

#### Scenario: Explicit startup subset preserves order
- **WHEN** the Hub starts processes after the Registry
- **THEN** it starts `assetaz.ticker.default`, `evelyn.service.prod`, `evelyn.service.test`, `evelyn.iou-burner.prod`, and `evelyn.mission-control.default` in that order

#### Scenario: Deliberately inactive processes remain inactive
- **WHEN** Hub startup reaches its online point
- **THEN** `jupiter-perps-alarm.default` and the dormant Composer, Process Manager, Test Tool, Soda Task Manager, and Suwimo Client paths have not been started

#### Scenario: Hub start is not retried
- **WHEN** any first Hub startup attempt has begun and `start()` is requested again
- **THEN** the later request fails with `IllegalStateException` whether the first attempt succeeded or failed

#### Scenario: Startup failure is fail-fast
- **WHEN** a process startup throws
- **THEN** the exception propagates, no later process starts, the Hub neither announces online nor enters its final wait, and no generic rollback or retry is attempted

### Requirement: Started-process snapshots are ordered immutable and truthful
`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. 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.

#### Scenario: Snapshot before process startup
- **WHEN** the snapshot is requested before any process has started successfully
- **THEN** it is an empty immutable list

#### Scenario: Successful process is recorded
- **WHEN** a process's `start()` call returns successfully
- **THEN** its ID appears after all previously successful process IDs in every later snapshot

#### Scenario: Failed process is not recorded
- **WHEN** a process's `start()` call throws
- **THEN** its ID is absent while all earlier successful process IDs remain visible

#### Scenario: Snapshot is a point-in-time value
- **WHEN** the Hub starts another process after a caller obtained a snapshot
- **THEN** the earlier snapshot is unchanged and cannot be mutated by its caller