elsa-core/doc/agent-logs/cshells-changes-summary.md

Summary of CShells Changes

There were two separate runtime problems I was addressing in CShells:

1. Duplicate endpoint registration during startup

   • This surfaced as: System.InvalidOperationException: Not allowed to configure endpoints after startup! Culprit: [Verbs()]
   • The root cause was that shell endpoints were getting mapped once during per-shell activation and then mapped again during the startup-wide ShellsReloaded flow.

2. Ambiguous activation of WebRoutingShellResolver

   • This surfaced as: Unable to activate type 'CShells.AspNetCore.Resolution.WebRoutingShellResolver'. The following constructors are ambiguous: ...
   • The root cause was that dependency injection could satisfy more than one constructor, so type-based activation was ambiguous.

---

src/CShells.AspNetCore/Configuration/CShellsBuilderExtensions.cs

What changed

I made two important changes here.

1. Switched web-routing resolver registration from type-based to factory-based creation

Instead of registering WebRoutingShellResolver by type alone, I changed the resolver pipeline registration to explicitly construct it with:

• IShellHost
• WebRoutingShellResolverOptions

2. Changed endpoint-registration notification wiring to one shared concrete handler plus per-notification forwarders

Previously, ShellEndpointRegistrationHandler was registered separately as:

• INotificationHandler<ShellActivated>
• INotificationHandler<ShellDeactivating>
• INotificationHandler<ShellRemoved>
• INotificationHandler<ShellsReloaded>

I changed that to:

• register one singleton ShellEndpointRegistrationHandler
• register small forwarders for each notification type:
  • ShellActivatedEndpointRegistrationForwarder
  • ShellDeactivatingEndpointRegistrationForwarder
  • ShellRemovedEndpointRegistrationForwarder
  • ShellsReloadedEndpointRegistrationForwarder

Why I did that

The factory-based resolver registration was to fix the WebRoutingShellResolver constructor ambiguity. Since DI could resolve multiple constructors, it was not safe to rely on type activation. Explicit construction forces one intended activation path.

The forwarder-based notification registration was needed because the endpoint deduplication logic depends on shared in-memory state. Registering the same implementation separately for multiple closed generic interfaces can lead to different singleton instances being used per interface type. That breaks state sharing.

By routing all notifications through one shared concrete ShellEndpointRegistrationHandler, the deduplication state is preserved across ShellActivated, ShellDeactivating, ShellRemoved, and ShellsReloaded.

---

src/CShells.AspNetCore/Notifications/ShellEndpointRegistrationHandler.cs

What changed

This file contains the main startup-endpoint fix.

I added:

• an optional IShellRuntimeStateAccessor
• a lock-protected dictionary of tracked applied generations
• helper methods to:
  • track generations
  • forget generations
  • reset tracked generations
• an IsEndpointGraphCurrent(...) guard

I also changed notification handling so that:

• ShellActivated registers endpoints and tracks the applied generation
• ShellDeactivating removes endpoints and forgets the generation
• ShellRemoved removes endpoints and forgets the generation
• ShellsReloaded now:
  • filters to routable shells
  • checks whether the current endpoint graph is already current
  • skips rebuild if nothing changed
  • otherwise clears and rebuilds the full endpoint graph and retracks generations

Finally, I added the forwarder classes at the bottom of the file.

Why I did that

This was the core fix for the duplicate startup endpoint-registration path.

The failure mode was effectively:

1. A shell becomes active
2. Its endpoints are mapped
3. A startup-wide ShellsReloaded is published
4. All shell endpoints are rebuilt again

That second pass was a problem for FastEndpoints, which rejects endpoint configuration after startup has progressed beyond its expected window.

To fix that, I made ShellEndpointRegistrationHandler state-aware. It now checks whether the currently mapped shell IDs and applied generations already match runtime state. If so, it skips the aggregate rebuild instead of remapping the same endpoints again.

That preserves the ability to rebuild endpoints when shells truly change, while avoiding no-op startup remaps.

---

src/CShells/Hosting/ShellStartupHostedService.cs

What changed

I changed startup publication of ShellsReloaded to use a custom notification strategy:

• startupShellsReloadedStrategy

I also added a private StartupShellsReloadedNotificationStrategy implementation that filters out ASP.NET Core notification handlers during the startup ShellsReloaded publication.

Why I did that

This was a startup-specific safety measure.

Even after adding deduplication logic, I wanted to prevent the startup-wide ShellsReloaded from immediately driving the ASP.NET Core endpoint-remapping path in the same startup cycle.

The intent was:

• keep publishing ShellsReloaded as a meaningful system event
• avoid redundant ASP.NET Core endpoint registration work during startup
• preserve other non-ASP.NET-Core ShellsReloaded observers

So this was not a general suppression of ShellsReloaded; it was a targeted startup filter to avoid duplicate endpoint mapping during application bootstrap.

---

src/CShells/Resolution/ResolverPipelineBuilder.cs

What changed

I added support for registering resolver strategies with a factory:

• Use<TStrategy>(Func<IServiceProvider, TStrategy> factory, int? order = null)

I also updated internal strategy registration so each strategy registration can now hold:

• a type
• an instance
• or a factory

During pipeline build, the resolver strategy can now be registered using that explicit factory.

Why I did that

This was necessary to support the explicit-construction fix for WebRoutingShellResolver in CShellsBuilderExtensions.

Once I decided not to rely on DI constructor selection for that resolver, the pipeline needed a way to say:

register this resolver strategy, but instantiate it exactly this way

Without factory support in ResolverPipelineBuilder, there was no clean way to do that.

---

Supporting Test Changes

These test changes matter because they encode the design intent behind the production changes.

tests/CShells.Tests/Integration/AspNetCore/ApplicationBuilderExtensionsTests.cs

What changed

I added a regression test that verifies:

• after a shell is activated and endpoints are mapped,
• a subsequent ShellsReloaded with the same applied generation state
• does not remap the endpoints again

I also added:

• a counting web feature
• a simple endpoint mapping counter

Why I did that

Because the production bug was about duplicate endpoint registration, I wanted a test that directly proves the bad sequence no longer happens.

The test protects the scenario that previously triggered the FastEndpoints startup exception.

---

tests/CShells.Tests/Integration/AspNetCore/ServiceCollectionExtensionsTests.cs

What changed

I added a regression test that verifies the DI registration shape now consists of:

• one concrete ShellEndpointRegistrationHandler
• forwarders registered for each notification interface

Why I did that

The shared-state design only works if all notification types ultimately delegate to the same concrete handler instance.

This test protects that registration shape so it is not accidentally simplified back into a broken form later.

---

Overall Rationale

The CShells changes were meant to make startup behavior more correct and deterministic.

For endpoint registration

I was trying to prevent this sequence:

• shell activates
• endpoints are mapped
• startup-wide reload fires
• endpoints are rebuilt again
• FastEndpoints rejects the second configuration pass

So I:

• added endpoint graph/generation tracking
• ensured the tracking state is actually shared across notification types
• skipped unnecessary aggregate rebuilds
• added a startup-specific filter as a safety measure

For web routing

I was trying to prevent DI from making an ambiguous constructor choice when building WebRoutingShellResolver.

So I:

• stopped relying on type-based activation
• added factory-based resolver registration support
• explicitly constructed the resolver with the intended dependencies

---

Net Effect

These changes were intended to move CShells away from startup behavior that depended on:

• duplicate lifecycle-triggered endpoint registration
• DI constructor-selection heuristics

and toward behavior that is:

• state-aware
• deduplicated
• explicitly constructed where necessary

That is why each of those CShells files changed the way they did.