Strongly-typed actor IDs and actor-specific bus overloads

Every actor now has a typed ID wrapper — including string-keyed actors like Account(string id)
which get Account.NewId("1") — making it impossible to route a message to the wrong actor or
forget to prefix the raw grain key. Bus overloads are actor-specific: only the messages each
actor actually handles appear as typed Execute/Query extension methods on that actor's ID type,
giving full compile-time safety and accurate IntelliSense.

Author: kzu

AGENTS.md

@@ -156,7 +156,7 @@ Emits OpenTelemetry spans (using `ActivitySource`) and metrics (using `Meter`) f
 
 | Package | Generators | Runs in |
 |---------|-----------|---------|
-| `CloudActors.Abstractions.CodeAnalysis` | `ActorStateGenerator`, `ActorMessageGenerator`, `ActorIdBusOverloadGenerator`, `ActorBusOverloadGenerator`, `ActorPrimitiveIdGenerator`, `EventSourcedGenerator`, `CloudActorsAttributeGenerator` | Actor domain class library |
+| `CloudActors.Abstractions.CodeAnalysis` | `ActorStateGenerator`, `ActorMessageGenerator`, `ActorBusOverloadGenerator`, `ActorPrimitiveIdGenerator`, `EventSourcedGenerator`, `CloudActorsAttributeGenerator` | Actor domain class library |
 | `CloudActors.CodeAnalysis` | `ActorGrainGenerator`, `ActorIdFactoryGenerator`, `ActorsAssemblyGenerator` | Orleans silo / host project |
 
 ### Incremental pipeline conventions
@@ -201,20 +201,30 @@ Filters out generic types (`!x.IsGenericType`) and internal/special types to avo
 
 Uses `CompilationProvider.Select` to discover all actors with typed IDs and generates an `IActorIdFactory` implementation registered via `[ModuleInitializer]` through `ActorIdFactory.Generated`.
 
-### ActorIdBusOverloadGenerator (`CloudActors.Abstractions.CodeAnalysis`)
+### ActorBusOverloadGenerator (`CloudActors.Abstractions.CodeAnalysis`)
 
-Generates typed `IActorBus` extension methods for actors with non-string IDs. Two cases:
-- **Primitive ID** (e.g. `long`, `Guid`): uses the generated `{Actor}.{Actor}Id` wrapper type
-- **Typed ID** (e.g. `ProductId`): uses the actual ID type directly
+Generates strongly-typed, **actor-specific** `IActorBus` extension methods. For each actor, only the messages it actually handles (via declared handler methods) get typed overloads. Uses `CreateSyntaxProvider` to find `[Actor]` classes in the current project.
 
-To avoid `CS0111`, overloads are **only generated for ID types used by exactly one actor**. If two actors share the same underlying primitive type, no typed overloads are emitted.
+ID parameter type depends on the actor's ID:
+- **String or primitive ID** (`string`, `long`, `Guid`, …): uses the generated `{Actor}.{Actor}Id` wrapper; routes to `$"actortype/{id.Id}"`. All actors whose first constructor parameter is a BCL primitive or `string` go through this path — there are never plain `string` bus overloads.
+- **Typed ID** (`IParsable<T>` / `IStructId<T>`): uses the ID type directly; routes to `$"actortype/{id}"`.
+- **No recognized ID**: no overloads are emitted (unreachable for any valid `[Actor]` class).
+
+One file per actor (`{Actor}.Bus.g.cs`) containing all its overloads:
+- Void command → `Task ExecuteAsync(IActorBus, Id, Msg)`
+- Command with return → `Task<T> ExecuteAsync(IActorBus, Id, Msg)`
+- Query → `Task<T> QueryAsync(IActorBus, Id, Msg)`
+
+**Important**: `IActorCommand<T>` extends `IActorCommand`, so message types implementing `IActorCommand<T>` satisfy both `IsActorCommand()` (generic) and `IsActorVoidCommand()` (non-generic). The `voidCommands` extraction explicitly excludes types that also pass `IsActorCommand()` to keep the two buckets mutually exclusive.
 
 ### ActorPrimitiveIdGenerator (`CloudActors.Abstractions.CodeAnalysis`)
 
-For actors whose primary constructor takes a primitive BCL value type (e.g. `long`, `Guid`), generates:
-- A nested `readonly record struct {Actor}Id(T Id)` wrapper
-- A static `NewId(T id)` factory method
-- For `Guid` IDs: an additional parameterless `NewId()` that calls `Guid.CreateVersion7()` (if available on the runtime) or `Guid.NewGuid()`
+For actors whose primary constructor takes **any BCL primitive or `string`** (e.g. `string`, `long`, `Guid`), generates a nested typed wrapper and factory:
+- `readonly record struct {Actor}Id(T Id)` — e.g. `AccountId(string Id)`, `OrderId(long Id)`
+- `static {Actor}Id NewId(T id)` factory method
+- For `Guid` IDs only: an additional parameterless `NewId()` using `Guid.CreateVersion7()` (.NET 9+) or `Guid.NewGuid()`
+
+This covers **all** actors with BCL-typed constructor IDs, including string-keyed ones. A string actor like `Account(string id)` gets `Account.AccountId(string Id)` and `Account.NewId("1")`, ensuring callers cannot accidentally pass a raw prefixed grain key (`"account/1"`) to the wrong actor.
 
 ### EventSourcedGenerator (`CloudActors.Abstractions.CodeAnalysis`)
 
@@ -243,11 +253,12 @@ Helper that discovers and invokes the STJ (`System.Text.Json`) source generator
 
 ## Typed Actor IDs
 
-Actors can use non-string IDs in three ways:
+Every actor has a strongly-typed ID — CloudActors never emits plain `string` bus overloads. The ID flavor depends on the actor's constructor:
+
+1. **BCL primitive or string** (`string`, `long`, `Guid`, …): `ActorPrimitiveIdGenerator` generates a nested `{Actor}Id(T Id)` wrapper struct. Both `Account(string id)` and `Order(long id)` fall into this category; callers use `Account.NewId("1")` / `Order.NewId(42)`.
+2. **Structured / library ID** (`IParsable<T>` / `IStructId<T>`): The ID type is used directly in bus overloads (e.g. `ProductId`). Works automatically with [StructId](https://github.com/devlooped/StructId), StronglyTypedId, Vogen, etc.
 
-1. **Primitive ID** (`long`, `Guid`, etc.): A nested `{Actor}Id` wrapper struct is generated; `NewId()` helper is available.
-2. **Typed ID** via `IParsable<T>` / `IFormattable`: The ID type (e.g. `ProductId`) is used directly. Typed `IActorBus` extension overloads are generated.
-3. **StructId**: Types implementing `IStructId` (from the [StructId](https://github.com/devlooped/StructId) package) are detected automatically.
+All actors have typed IDs, providing compile-time safety against passing the wrong message to the wrong actor.
 
 ID format stored in Orleans: `"{actortype}/{id}"` (e.g. `"account/42"`, `"product/p1"`).
 

readme.md

@@ -315,7 +315,35 @@ project, and more incremental behavior added as users opt-in to certain features
 
 ## Typed Actor IDs
 
-Instead of identifying actors with plain strings, you can use strongly-typed IDs.
+All actors get a strongly-typed IDs for free — CloudActors emits proper typed overloads so 
+you never have to use raw `string` composite keys for bus calls, which prevents accidentally 
+passing the wrong ID format (e.g. `"account/1"` vs. `"1"`).
+
+### String IDs
+
+When the actor's first constructor parameter is `string`, the generator produces a `{Actor}Id` 
+wrapper struct so callers use type-safe IDs against the bus, while getting useful completion from 
+overloads exposing the applicable messages the actor can handle:
+
+```csharp
+[Actor]
+public partial class Account(string id)
+{
+    public string Id { get; } = id;
+    // ...
+}
+
+// Generated:
+//   public readonly record struct AccountId(string Id);
+//   public static AccountId NewId(string id) => new(id);
+```
+
+```csharp
+var id = Account.NewId("1");
+
+await bus.ExecuteAsync(id, new Deposit(100));
+var balance = await bus.QueryAsync(id, GetBalance.Default);
+```
 
 ### Primitive IDs
 
@@ -379,18 +407,20 @@ var price = await bus.QueryAsync(id, new GetPrice());
 
 ### Typed Bus Overloads
 
-For any actor with a typed ID (primitive or structured), the generator produces typed 
-`IActorBus` extension overloads so you never have to format the ID string manually:
+For every actor, the generator produces typed `IActorBus` extension overloads — one per 
+handled message — so you can never accidentally pass the wrong message to the wrong actor:
 
 ```csharp
-// Instead of:
-await bus.ExecuteAsync("order/42", new PlaceOrder(...));
-
-// You can use the typed overload:
+// Only valid messages for Order are available via OrderId:
 await bus.ExecuteAsync(new OrderId(42), new PlaceOrder(...));
+
+// Compile error: Deposit is not a valid message for Order
+await bus.ExecuteAsync(new OrderId(42), new Deposit(100)); // ❌
 ```
 
-The ID is always stored and routed as `"{actortype}/{id}"` (e.g. `"order/42"`, `"product/..."`).
+The ID is always routed as `"{actortype}/{id}"` (e.g. `"order/42"`, `"product/..."`) 
+as expected by Orleans, but the typed overloads shield you from that detail and provide 
+type safety.
 
 ## Telemetry and Monitoring
 

src/CloudActors.Abstractions.CodeAnalysis/ActorBusOverloadGenerator.cs

@@ -1,92 +1,150 @@
 using System.Linq;
+using System.Text;
 using Microsoft.CodeAnalysis;
 using Microsoft.CodeAnalysis.CSharp.Syntax;
-using static Devlooped.CloudActors.AnalysisExtensions;
 
 namespace Devlooped.CloudActors;
 
+/// <summary>
+/// Generates strongly-typed, message-specific <see cref="IActorBus"/> extension methods for each actor.
+/// For actors with a typed ID, emits (TypedId, ConcreteMessage) overloads.
+/// For actors with a string ID, emits (string, ConcreteMessage) overloads.
+/// Only messages actually handled by the actor (declared handler methods) get overloads.
+/// </summary>
 [Generator(LanguageNames.CSharp)]
 class ActorBusOverloadGenerator : IIncrementalGenerator
 {
     public void Initialize(IncrementalGeneratorInitializationContext context)
     {
-        var interfaces = context.CompilationProvider
-            .Select((c, _) => (
-                VoidCommand: c.GetTypeByMetadataName("Devlooped.CloudActors.IActorCommand")?.ToDisplayString(FullName),
-                Command: c.GetTypeByMetadataName("Devlooped.CloudActors.IActorCommand`1")?.ToDisplayString(FullName),
-                Query: c.GetTypeByMetadataName("Devlooped.CloudActors.IActorQuery`1")?.ToDisplayString(FullName)))
-            .WithTrackingName(TrackingNames.BusInterfaces);
-
-        var messages = context.SyntaxProvider.CreateSyntaxProvider(
+        var actors = context.SyntaxProvider.CreateSyntaxProvider(
             predicate: static (node, _) =>
-                node is TypeDeclarationSyntax tds &&
-                tds.BaseList?.Types.Count > 0,
+                node is ClassDeclarationSyntax cds &&
+                cds.AttributeLists.Count > 0,
             transform: static (ctx, ct) =>
             {
-                if (ctx.SemanticModel.GetDeclaredSymbol(ctx.Node, ct) is not INamedTypeSymbol type)
-                    return default;
+                if (ctx.SemanticModel.GetDeclaredSymbol(ctx.Node, ct) is not INamedTypeSymbol symbol)
+                    return (ActorModel?)null;
 
-                if (!type.IsActorMessage())
-                    return default;
+                if (!symbol.IsActor())
+                    return null;
 
-                var voidCommand = ctx.SemanticModel.Compilation.GetTypeByMetadataName("Devlooped.CloudActors.IActorCommand");
-                var command = ctx.SemanticModel.Compilation.GetTypeByMetadataName("Devlooped.CloudActors.IActorCommand`1");
-                var query = ctx.SemanticModel.Compilation.GetTypeByMetadataName("Devlooped.CloudActors.IActorQuery`1");
+                var iParsable = ctx.SemanticModel.Compilation.GetTypeByMetadataName("System.IParsable`1");
+                var guidType = ctx.SemanticModel.Compilation.GetTypeByMetadataName("System.Guid");
+                var hasCreateVersion7 = guidType?.GetMembers("CreateVersion7")
+                    .OfType<IMethodSymbol>()
+                    .Any(m => m.IsStatic && m.Parameters.Length == 0) == true;
 
-                return ModelExtractors.ExtractActorMessageModel(type, voidCommand, command, query);
+                return ModelExtractors.ExtractActorModel(symbol, iParsable, hasCreateVersion7);
             })
             .Where(static x => x != null)
             .Select(static (x, _) => x!.Value)
             .WithTrackingName(TrackingNames.BusOverloads);
 
-        context.RegisterSourceOutput(messages, (ctx, model) =>
+        // Emit the base partial class only when at least one actor has emittable overloads.
+        // Using Collect+Select(bool) keeps this a single cached bool — not per-actor — so the
+        // base file is only added/removed when the set of emittable actors crosses zero.
+        var hasOverloads = actors
+            .Where(static a =>
+                (a.VoidCommands.Length > 0 || a.Commands.Length > 0 || a.Queries.Length > 0) &&
+                (a.IsPrimitiveId || a.IsTypedId))
+            .Collect()
+            .Select(static (arr, _) => arr.Length > 0);
+
+        context.RegisterSourceOutput(hasOverloads, static (ctx, hasAny) =>
+        {
+            if (!hasAny)
+                return;
+
+            ctx.AddSource("ActorBusExtensions.g.cs",
+                """
+                // <auto-generated/>
+                using System.ComponentModel;
+                [EditorBrowsable(EditorBrowsableState.Never)]
+                public static partial class ActorBusExtensions { }
+                """);
+        });
+
+        // Per-actor overloads remain incremental: each actor's file is independently cached.
+        context.RegisterSourceOutput(actors, (ctx, actor) =>
         {
-            var file = $"{model.FileName}.g.cs";
+            if (actor.VoidCommands.Length == 0 && actor.Commands.Length == 0 && actor.Queries.Length == 0)
+                return;
+
+            var grainType = actor.Name.ToLowerInvariant();
 
-            switch (model.Kind)
+            string busIdTypeName;
+            string idExpr;
+
+            if (actor.IsPrimitiveId)
+            {
+                busIdTypeName = $"{actor.FullName}.{actor.Name}Id";
+                idExpr = $"$\"{grainType}/{{id.Id}}\"";
+            }
+            else if (actor.IsTypedId && actor.IdTypeFullName != null)
             {
-                case ActorMessageKind.VoidCommand:
-                    ctx.AddSource(file,
-                        $$"""
-                        using System.Threading.Tasks;
-                        using Devlooped.CloudActors;
-                                            
-                        static partial class ActorBusExtensions
-                        {
-                            public static Task ExecuteAsync(this IActorBus bus, string id, {{model.FullName}} command)
-                                => bus.ExecuteAsync(id, (IActorCommand)command);
-                        }
-                        """);
-                    break;
-
-                case ActorMessageKind.Command:
-                    ctx.AddSource(file,
-                        $$"""
-                        using System.Threading.Tasks;
-                        using Devlooped.CloudActors;
-
-                        static partial class ActorBusExtensions
-                        {
-                            public static Task<{{model.ReturnTypeFullName}}> ExecuteAsync(this IActorBus bus, string id, {{model.FullName}} command)
-                                => bus.ExecuteAsync<{{model.ReturnTypeFullName}}>(id, command);
-                        }
-                        """);
-                    break;
-
-                case ActorMessageKind.Query:
-                    ctx.AddSource(file,
-                        $$"""
-                        using System.Threading.Tasks;
-                        using Devlooped.CloudActors;
-
-                        static partial class ActorBusExtensions
-                        {
-                            public static Task<{{model.ReturnTypeFullName}}> QueryAsync(this IActorBus bus, string id, {{model.FullName}} query)
-                                => bus.QueryAsync<{{model.ReturnTypeFullName}}>(id, query);
-                        }
-                        """);
-                    break;
+                busIdTypeName = actor.IdTypeFullName;
+                idExpr = $"$\"{grainType}/{{id}}\"";
             }
+            else
+            {
+                // Actor with no recognized ID type — no typed overloads can be generated.
+                return;
+            }
+
+            var sb = new StringBuilder();
+            sb.AppendLine("// <auto-generated/>");
+            sb.AppendLine("#nullable enable");
+            sb.AppendLine("using System.Runtime.CompilerServices;");
+            sb.AppendLine("using System.Threading.Tasks;");
+            sb.AppendLine("using Devlooped.CloudActors;");
+            sb.AppendLine();
+            sb.AppendLine("static partial class ActorBusExtensions");
+            sb.AppendLine("{");
+
+            foreach (var cmd in actor.VoidCommands.AsImmutableArray())
+            {
+                sb.AppendLine(
+                    $"    /// <summary>Invokes a state-changing command on a <see cref=\"{actor.FullName}\"/> actor.</summary>");
+                sb.AppendLine(
+                    $"    public static Task ExecuteAsync(this IActorBus bus, {busIdTypeName} id, {cmd.Type} command,");
+                sb.AppendLine(
+                    $"        [CallerMemberName] string? callerName = default, [CallerFilePath] string? callerFile = default, [CallerLineNumber] int? callerLine = default)");
+                sb.AppendLine(
+                    $"        => bus.ExecuteAsync({idExpr}, (IActorCommand)command, callerName, callerFile, callerLine);");
+                sb.AppendLine();
+            }
+
+            foreach (var cmd in actor.Commands.AsImmutableArray())
+            {
+                var returnType = cmd.ReturnTypeFullName!;
+                sb.AppendLine(
+                    $"    /// <summary>Invokes a state-changing command on a <see cref=\"{actor.FullName}\"/> actor.</summary>");
+                sb.AppendLine(
+                    $"    public static Task<{returnType}> ExecuteAsync(this IActorBus bus, {busIdTypeName} id, {cmd.Type} command,");
+                sb.AppendLine(
+                    $"        [CallerMemberName] string? callerName = default, [CallerFilePath] string? callerFile = default, [CallerLineNumber] int? callerLine = default)");
+                sb.AppendLine(
+                    $"        => bus.ExecuteAsync<{returnType}>({idExpr}, command, callerName, callerFile, callerLine);");
+                sb.AppendLine();
+            }
+
+            foreach (var query in actor.Queries.AsImmutableArray())
+            {
+                var returnType = query.ReturnTypeFullName!;
+                sb.AppendLine(
+                    $"    /// <summary>Invokes a read-only query on a <see cref=\"{actor.FullName}\"/> actor.</summary>");
+                sb.AppendLine(
+                    $"    public static Task<{returnType}> QueryAsync(this IActorBus bus, {busIdTypeName} id, {query.Type} query,");
+                sb.AppendLine(
+                    $"        [CallerMemberName] string? callerName = default, [CallerFilePath] string? callerFile = default, [CallerLineNumber] int? callerLine = default)");
+                sb.AppendLine(
+                    $"        => bus.QueryAsync<{returnType}>({idExpr}, query, callerName, callerFile, callerLine);");
+                sb.AppendLine();
+            }
+
+            sb.AppendLine("}");
+
+            ctx.AddSource($"{actor.FileName}.Bus.g.cs", sb.ToString());
         });
     }
 }