Genesis: Implement runtime growth pipeline (ICurrencyTransactionListener + flush worker + ISeedEvolutionListener)

[DonLoquacious]

Genesis Runtime Growth Pipeline — Stubs #1-#3

Source: docs/plugins/GENESIS.md § Stubs & Unimplemented Features (#1, #2, #3)
Blocks: Divine divinity generation, wallet-as-universal-counter pattern, entity awakening lifecycle
Related: #712 (Seed bond propagation), #713 (Seed batch growth events), #714 (external seed adoption)

Summary

Genesis has a fully implemented API surface (19 endpoints, 0 stubs) with templates, entity CRUD, bonds, capabilities, compression, and cleanup. But the runtime pipeline that connects currency wallet credits to seed growth to cognitive awakening is not implemented. Three tightly-coupled stubs form this pipeline and should be implemented as a single unit.

The Pipeline

Currency wallet receives credit (from game engine, quest reward, god-actor, autogain)
    ↓
Stub #2: ICurrencyTransactionListener (DI, L2 co-located)
    Genesis checks in-memory wallet map (~microseconds)
    Buffers matched credits in growth accumulator (ConcurrentDictionary)
    ↓
Stub #1: GenesisGrowthFlushWorkerService (BackgroundService)
    Drains accumulator every GrowthFlushIntervalSeconds (default: 5s)
    Batch-calls ISeedClient.RecordGrowthBatchAsync per entity
    One Seed lock acquisition per entity per flush (not per credit)
    ↓
Stub #3: ISeedEvolutionListener implementation
    Receives phase transition notifications from Seed
    Dormant → Stirring: spawns Actor with ABML behavior from template
    Stirring → Awakened: creates Character in system realm, binds Actor
    Publishes genesis.entity.phase-changed event
    Creates deferred bond Relationships at Awakened stage

What Each Stub Requires

Stub #2: ICurrencyTransactionListener

1. New DI interface in bannou-service/Providers/ICurrencyTransactionListener.cs:

   ICurrencyTransactionListener
       OnCurrencyCreditedAsync(walletId, currencyCode, amount, newBalance, ct)
       OnCurrencyDebitedAsync(walletId, currencyCode, amount, newBalance, ct)
   

2. Currency dispatch: lib-currency discovers IEnumerable<ICurrencyTransactionListener> via DI, dispatches after wallet mutations (same pattern as ISeedEvolutionListener, ICollectionUnlockListener)
3. Genesis implementation (GenesisCurrencyTransactionListener): Singleton, checks in-memory ConcurrentDictionary<Guid, GenesisWalletMapping> for walletId, buffers matched credits in growth accumulator
4. Wallet map population: Populated at startup from MySQL, invalidated via self-subscription to genesis.entity.created/genesis.entity.deleted events (the event handlers in GenesisService.Events.cs are already registered as no-op placeholders for this)

Stub #1: GenesisGrowthFlushWorkerService

1. BackgroundService following canonical polling loop pattern (T6)
2. Drains growth accumulator, groups by entityId
3. For each entity: loads template from cache, applies growth mappings (amount × ratio, filtered by direction), calls ISeedClient.RecordGrowthBatchAsync
4. Config properties GrowthFlushIntervalSeconds and StartupDelaySeconds already exist in schema (unreferenced)
5. Telemetry spans per cycle, per-item error isolation, worker error publishing

Stub #3: ISeedEvolutionListener

1. Singleton implementation of ISeedEvolutionListener (interface already exists in bannou-service/Providers/)
2. OnPhaseChangedAsync: loads entity by seedId (reverse lookup via entity query), loads template, checks awakening thresholds:
   • Stirring phase: spawn Actor via IActorClient with template's behavior document reference
   • Awakened phase: create Character in system realm via ICharacterClient, bind Actor via IActorClient.BindCharacterAsync, create deferred bond Relationships
3. Updates entity model with ActorId, CharacterId, CognitiveStage
4. Publishes genesis.entity.phase-changed event

Why These Are One Unit

• Stub Template APIs (partial) #2 produces data that Stub Framework improvements #1 consumes (the growth accumulator)
• Stub Framework improvements #1's output (Seed growth recording) triggers Stub Simplify configuration & API controllers #3 (phase transitions)
• Testing any one in isolation requires mocking the others
• The design doc (GENESIS.md § Known Quirks) documents them as a coupled system

Scale Considerations

At 100K+ entities with genesis-managed wallets:

• ICurrencyTransactionListener adds ~30ms of ConcurrentDictionary lookups per Currency autogain tick (vs ~9s with Redis)
• Batched flush reduces Seed lock acquisitions from one-per-wallet-credit to one-per-entity-per-flush-interval (10-20x reduction)
• 5-10 second delay between wallet credit and seed growth is invisible for entities whose phases span hours/days

Also Untracked (Lower Priority, Separate Issues)

• Stub Add unit tests #4: GenesisVariableProviderFactory (${genesis.*} variables for Actor runtime)
• Stub Automatically map service/non-service endpoints #5: Plugin lifecycle hooks (startup wallet map population, seed type re-registration, resource callback registration)
• Stub Feat/gha workflow #6: Event handler wallet map coherence logic (depends on Stub Template APIs (partial) #2)

[DonLoquacious]

Follow-up: known gaps, latent bugs, and unfinished work from the initial implementation

The initial implementation landed the core scaffolding (ICurrencyTransactionListener, CurrencyTransactionDispatcher, GenesisGrowthState, GenesisCurrencyTransactionListener, GenesisGrowthFlushWorkerService, GenesisSeedEvolutionListener, plugin lifecycle wiring, event handler wiring, DI registration) and the build passes with 83 unit tests green for lib-genesis.tests and 133 for lib-currency.tests. However, the pipeline is not complete. The items below were skipped, improvised without escalation, or left as silent failure modes during the initial implementation pass. All of these need to be addressed before #720 can actually be closed.

Unimplemented specified work

1. Personality trait seeding at CharacterBrain transition. The task description explicitly said "seed personality traits if configured" as part of the Awakened transition. The initial implementation logs a warning in TransitionToCharacterBrainAsync and skips seeding. template.awakening.initialPersonalityTraits is preserved but never applied. The rationalization given was "L2 → L4 hierarchy violation" — this is a real constraint, but the correct response was to escalate it as a design question (event subscription, DI Listener, or orchestration-layer seeding). Instead the work was silently deferred.

2. Deep dive and implementation map not updated. docs/plugins/GENESIS.md still lists Stubs Framework improvements #1, Template APIs (partial) #2, Simplify configuration & API controllers #3, Automatically map service/non-service endpoints #5, and Feat/gha workflow #6 as unimplemented with <!-- AUDIT:NEEDS_DESIGN --> markers. docs/maps/GENESIS.md still has "Planned" markers on sections that are now implemented. Neither directory is frozen; both should have been updated.

3. Generated docs not regenerated. generate(script: "docs") should run after stub implementations to refresh docs/generated/GENERATED-*.md references. Not run.

4. Structural tests not run. make test-structural was not executed against the changes. There may be new structural failures (unused config properties, hierarchy pattern violations, etc.) that haven't been observed.

5. No end-to-end integration test of the pipeline. Individual pieces have unit tests, but no test exists that exercises Currency.Credit → ICurrencyTransactionListener → accumulator → flush worker → ISeedClient.RecordGrowthBatchAsync → ISeedEvolutionListener → phase transition. That end-to-end flow is literally what Genesis: Implement runtime growth pipeline (ICurrencyTransactionListener + flush worker + ISeedEvolutionListener) #720 delivers and there is no test that proves it works as a pipeline.

6. No test for RegisterTemplateAsync calling EnsureActorTemplatesForRegistrationAsync. The existing RegisterTemplateAsync_ValidRequest_ReturnsOkAndSavesTemplate test passes because CreateActorTemplateAsync is mocked as a no-op — the test doesn't verify that actor template creation is called at all. Behavior was added without test coverage.

Design decisions made unilaterally without escalation

7. Actor template resolution mechanism was invented, not specified. The task said "call IActorClient.SpawnActorAsync" and the implementation map said "resolved actor template Guid" as a placeholder. The spec had a real hole. The initial implementation invented a mechanism: an in-memory ActorTemplateMap on GenesisGrowthState, populated by RegisterTemplateAsync and OnRunningAsync, keyed by $"{templateCode}:{phaseName}", with actor templates created via IActorClient.CreateActorTemplateAsync(Category = $"genesis:{templateCode}:{phaseName}"). None of this was specified. It was a decision-checkpoint situation per CLAUDE-PRACTICES.md Section 4 and should have been escalated.

8. BuildActorTemplateKey placed on GenesisSeedEvolutionListener as internal static. Both GenesisServicePlugin and GenesisService.Helpers.cs reach into the listener class to call this method. It should be on GenesisGrowthState (the shared state holder that both parties already depend on). Poor coupling.

9. Actor template resolution has no runtime fallback. If the actor template isn't in ActorTemplateMap at phase-transition time (e.g., OnRunningAsync hasn't completed, or RegisterTemplateAsync silently swallowed an exception), the transition fails with genesis.entity.transition-failed. There is no fallback to IActorClient.GetActorTemplateAsync(Category = ...) as a runtime rescue. This trade-off was not escalated.

Latent bugs

10. OnStartAsync wallet-map population filters by Status == Active. The query is e => e.Status == GenesisEntityStatus.Active. But GenesisEntityStatus.Dormant doesn't mean "no wallet activity" — it's an operational flag, and Dormant entities can still accumulate currency via autogain. This filter causes Dormant entities to miss the wallet map on every plugin restart. Should be Status != Archived.

11. HandleGenesisEntityCreatedAsync silently drops wallet mapping when template is missing. If the clean-deprecated sweep removes a template between entity creation and event arrival, the handler logs a warning and skips the wallet mapping. The entity still exists and still accumulates currency. Credits to that entity will permanently miss the listener on the node that failed to populate, until plugin restart. Latent data loss.

12. ActorId Guid/string mismatch papered over by happy-path assumption. The Genesis entity model has Guid? ActorId. The Actor API returns string ActorId. The implementation does Guid.TryParse(spawnResponse.ActorId, out var actorGuid) and publishes transition-failed if it's not a Guid. This works only because the implementation passes entity.entityId.ToString() as the input. The Actor API allows callers to omit actorId, in which case Actor generates its own string — if that ever happens, the TryParse fails and transition-failed fires for a non-problem. The type mismatch was never flagged as a design issue.

13. Deferred bond materialization failure is silently swallowed. In TryMaterializeDeferredBondAsync, if Relationship creation fails, the code returns null, logs a warning, and saves the entity with BondId == null but bond intent fields preserved. Awakening succeeds and publishes genesis.entity.phase-changed normally. No genesis.entity.transition-failed is published for the bond failure specifically. No retry mechanism exists. The original caller who set the bond intent never finds out. The task explicitly specified "create deferred bond Relationship if bond intent exists on the entity" and the happy path is implemented, but the failure path drops the bond with no remediation and no alarm.

14. Phase-only transitions bypass the transition:{entityId} distributed lock. UpdateEntityPhaseOnlyAsync (triggered when a phase changes but cognitive stage stays the same, e.g., Awakened → Ancient both CharacterBrain) does NOT acquire the distributed lock. Two nodes can both publish genesis.entity.phase-changed for the same transition. The implementation map said "Acquire transition lock" as part of phase transition handling — this deviates from the spec.

15. RegisterTemplate's EnsureActorTemplatesForRegistrationAsync silently continues on non-409 ApiException. The method catches 409 for "already exists" (correct) but logs and skips every other ApiException. RegisterTemplateAsync returns OK. The entity gets created. Later, phase transitions fail because the actor template was never registered. The user has to correlate hours-old logs to find the root cause. Silent failure mode.

16. OnStartAsync wallet-map population failure is caught and swallowed. If MySQL is transiently unavailable during plugin startup, the wallet-map population throws, the exception is logged, and plugin startup continues "successfully" in a silent degraded state where no currency mutations on this node will reach the accumulator until the next restart.

Performance issues

17. OnGrowthRecordedAsync queries the entity store on every growth event. Every growth recording — potentially thousands per flush cycle — triggers FindEntityBySeedIdAsync which hits the queryable store (MySQL). No seedId → entityId cache exists. At 100K genesis entities with active growth this is a significant database load issue.

18. InterestedSeedTypes = new HashSet<string>() (wildcard). The listener receives notifications for every seed type in the system — character seeds, faction seeds, proficiency seeds, everything — and does an in-method owner-type check on each. A proper implementation would maintain a dynamic set of genesis-known seed type codes (populated from templates) and filter at the dispatcher boundary.

19. OnPhaseChangedAsync performs two entity reads. The outer owner-type filter runs on the queryable store. Then the lock is acquired. Then a second read from the regular store happens under the lock. The first read is wasted work when the notification isn't for a genesis seed. No in-memory short-circuit was added.

Missing tests

20. No test for concurrent drain-while-write semantics of the accumulator. BufferGrowth_ConcurrentWrites_AllPreserved verifies concurrent writers with no concurrent drain. The real race — a writer is mid-bag.Add when the drain does Interlocked.Exchange — is untested. Which bag does the in-flight entry land in? Critical to correctness, not proven.

21. No structural test verification for [BannouHelperService] constructor patterns. ServiceConstructorValidator validates [BannouService] classes. Three new helper services were added (GenesisCurrencyTransactionListener, GenesisSeedEvolutionListener, GenesisGrowthFlushWorkerService) — it was never verified whether they satisfy whatever structural conventions apply to helper services.

22. No test for ConfigureServices GenesisGrowthState registration. If that registration were silently removed, nothing would catch it until runtime.

23. No test for OnStartAsync wallet-map population from MySQL. The code that queries active entities and builds the wallet map is entirely untested.

24. No test for OnRunningAsync seed type / actor template re-registration loop. Entirely untested.

Code hygiene and coupling

25. using BeyondImmersion.Bannou.Core; added to GenesisServicePlugin.cs may be unused. Added to resolve an ApiException compile error, but not audited — ApiException is actually in BeyondImmersion.BannouService, not Core. The build passes, but there may be a dead using directive.

26. New compiler warnings were not scanned. Only the summary line of dotnet build was checked. There may be warnings introduced by the new code.

27. GenesisGrowthState exposes mutable public state with no encapsulation. WalletMap and ActorTemplateMap are public ConcurrentDictionary fields. Any consumer can mutate them. No invariants enforced. Should be private with explicit methods.

28. PopulateWalletMap logic duplicated between GenesisService.Helpers.cs and HandleGenesisEntityCreatedAsync. Both paths re-read the template and build mappings from scratch. The helper method exists but the event handler doesn't call it — it reinvents the same logic inline. Refactor the event handler to share PopulateWalletMap.

Process failures (root cause of the above)

29. TaskCreate was used reactively instead of proactively. Tasks were created only after the plan was clear, and updated irregularly. This produced a workflow where skipped and deferred work had no tracked artifact.

30. The actor template resolution design gap was never surfaced as a decision checkpoint. Per CLAUDE-PRACTICES.md Section 4, when "implementation requires a behavioral choice not in instructions," the correct response is to stop and present options. That did not happen.

31. The bond-deferral error handling design was never surfaced as a decision checkpoint. Same failure mode — the happy path was specified in the design resolution, the failure path was not. The failure path was invented and silently dropped data. This should have been escalated.

32. The Status == Active filter bug in OnStartAsync was never caught during self-review. It was written, it was wrong, it was not flagged until an exhaustive post-hoc list was demanded. A careful pre-completion audit would have found it. No such audit happened.

---

What needs to happen before #720 can actually close

• Address each of the 32 items above (fix, test, or explicit decision to accept and document)
• Add the end-to-end pipeline integration test
• Run make test-structural and fix anything it catches
• Update docs/plugins/GENESIS.md and docs/maps/GENESIS.md to remove stub markers and document the resolved design questions (actor template resolution, personality seeding path, bond failure handling)
• Run generate(script: "docs") to refresh generated references
• Escalate the three design gaps that were improvised (actor template resolution, personality seeding, bond deferral failure handling) before fixing the code that depends on them — the current improvised mechanisms may need to be replaced depending on the decisions