182 lines
14 KiB
Markdown
182 lines
14 KiB
Markdown
# 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: Components and applications have minimal common contracts
|
|
`NenjimComponent` SHALL be a pure marker with no component-ID property. `NenjimApplication` SHALL extend `NenjimComponent` and expose only `start() throws Exception` as its common lifecycle operation. Domain service interfaces SHALL remain focused on their domain APIs, while a concrete service implementation with a no-argument active start lifecycle SHALL additionally implement `NenjimApplication`.
|
|
|
|
#### 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 start lifecycle
|
|
- **THEN** the implementation is discoverable as `NenjimApplication` without adding lifecycle operations solely to its domain service interface
|
|
|
|
#### Scenario: Common stop is unavailable
|
|
- **WHEN** a caller uses `NenjimApplication`
|
|
- **THEN** the contract exposes no common stop operation
|
|
|
|
### 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 application'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: Registry manager owns hardcoded composition and startup
|
|
`NenjimRegistryServiceManager` SHALL be a Nenjim component whose only public operation is `start() throws Exception`. Its public reference implementation SHALL be a distinct `NenjimApplication` object and SHALL accept only one start attempt, including after failure. The first attempt SHALL construct and directly start one Registry object, register that object first as `nenjim.registry.service`, register the manager second as `nenjim.registry.service-manager`, construct and register the complete required hardcoded component set in dependency order, start only the explicit active application subset in dependency-safe order, announce the existing online point, and preserve the existing blocking wait.
|
|
|
|
#### Scenario: Registry and manager views are registered
|
|
- **WHEN** manager composition reaches completed registration
|
|
- **THEN** the Registry object is retrievable by one ID as both `NenjimRegistryService` and `NenjimApplication`, the manager is retrievable by one different ID as both `NenjimRegistryServiceManager` and `NenjimApplication`, and the Registry and manager are different instances
|
|
|
|
#### Scenario: Required hardcoded bindings are registered
|
|
- **WHEN** manager composition completes
|
|
- **THEN** all component IDs and implementation choices enumerated by issue #76 are present exactly as configured, including intentionally inactive components
|
|
|
|
#### Scenario: Explicit startup subset preserves order
|
|
- **WHEN** the manager starts applications
|
|
- **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 applications remain inactive
|
|
- **WHEN** manager startup completes its explicit start sequence
|
|
- **THEN** `jupiter-perps-alarm.default` and the currently commented Composer, Process Manager, Test Tool, Soda Task Manager, and Suwimo Client are not started
|
|
|
|
#### Scenario: Manager start is not retried
|
|
- **WHEN** any first manager start attempt has begun and start is requested again
|
|
- **THEN** the later request fails with `IllegalStateException` whether the first attempt succeeded or failed
|
|
|
|
#### Scenario: Registration does not activate components
|
|
- **WHEN** the manager registers a component
|
|
- **THEN** registration alone neither starts nor stops that component
|
|
|
|
### 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 that does not implement `NenjimApplication`. Its `main(String[])` SHALL construct `NenjimRegistryServiceManagerImpl` through a variable typed as `NenjimApplication` and start it. The Gradle application entry point SHALL name this class. Construction, registration, composition, and lifecycle ownership SHALL remain in `NenjimRegistryServiceManagerImpl`; the bootstrap SHALL perform none of those responsibilities beyond constructing and starting the manager.
|
|
|
|
#### Scenario: Start through the outer bootstrap
|
|
- **WHEN** the configured Java entry point is invoked
|
|
- **THEN** `Main.main(...)` constructs one Registry manager as a Nenjim application and delegates startup to it
|
|
|
|
#### Scenario: No duplicate composition path remains
|
|
- **WHEN** the source tree is inspected after migration
|
|
- **THEN** the old Hub interface, `com.r35157.nenjim.hubd.impl.ref.Main`, and the `NenjimHubImpl` composition implementation are absent, while `com.r35157.nenjim.hubd.Main` contains no replacement composition path
|
|
|
|
### Requirement: Registry terminology and package boundaries are consistent
|
|
Public component contracts SHALL live in `com.r35157.nenjim.component`; public Registry service contracts SHALL live in `com.r35157.nenjim.service.registry`; the component ID SHALL live in its `.valuetypes` package; and internal administration and Registry storage SHALL live in `.impl.ref`. Directly affected Ticker price-source API and implementation packages SHALL use `.pricesource` rather than `.plugins.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
|
|
|
|
### 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.
|
|
|
|
#### Scenario: Consumer inspects the first Registry API
|
|
- **WHEN** a consumer examines the public Registry and manager contracts
|
|
- **THEN** only the agreed read-only lookup and manager start operations are available and no deferred feature is exposed
|