Merge branch 'type-id-redesign' into worktree_1

Author: mlidbom

dev_docs/TypeIdentifiers/TypeIdentifier-Design.md

@@ -1,18 +1,12 @@
-# Structural TypeId Design
+# TypeIdentifier Design
 
 > **No backward compatibility constraints.** There are zero deployed applications using this system. No persisted data exists. Any format, ID, or behavior can change freely.
 
 > **Draft.** Direction, not specification. The goal is a simpler, more transparent system — adjust as we go.
 
 ## Context
 
-The current TypeMapper replaces entire `$type` strings (e.g. `"System.Collections.Generic.List`1[[MyApp.MyEntity, MyApp]], System.Private.CoreLib"`) with opaque GUIDs. This requires:
-- Scanning every loaded assembly to discover all closed generic instantiations
-- Computing deterministic GUIDs for every closed generic and array type
-- Maintaining a global bidirectional dictionary of every type ever seen
-- A static singleton with assembly-load hooks
-
-All of this exists because the system flattens the *structurally recursive* type name into a *single opaque GUID*, then needs to reconstruct the full type from that GUID on deserialization.
+The previous TypeMapper replaced entire `$type` strings (e.g. `"System.Collections.Generic.List`1[[MyApp.MyEntity, MyApp]], System.Private.CoreLib"`) with opaque GUIDs. This required scanning every loaded assembly to discover all closed generic instantiations, computing deterministic GUIDs for every closed generic and array type, maintaining a global bidirectional dictionary of every type ever seen, and a static singleton with assembly-load hooks — all because the system flattened the *structurally recursive* type name into a *single opaque GUID*.
 
 ## Insight
 
@@ -74,32 +68,32 @@ For each `TypeName, Assembly` component:
 
 ### Caching
 
-Both directions are cached on the `ITypeMapper` instance:
-- **Serialize**: `Type` → `TypeId`. Once computed, subsequent serializations of the same type are a dictionary lookup.
-- **Deserialize**: `TypeId` string → `Type`. Once resolved, subsequent deserializations of the same string are a dictionary lookup.
+Both directions are cached on the `ITypeIdentifierMapper` instance:
+- **Serialize**: `Type` → `TypeIdentifier`. Once computed, subsequent serializations of the same type are a dictionary lookup.
+- **Deserialize**: `TypeIdentifier` string → `Type`. Once resolved, subsequent deserializations of the same string are a dictionary lookup.
 
 Parsing and tree-walking happen only on first encounter. Container-scoped caches are naturally garbage-collected with the container.
 
 ---
 
-## TypeId hierarchy
+## TypeIdentifier hierarchy
 
-`TypeId` is the identity of a fully constructed type. It is an abstract base with three concrete subtypes, each representing a different kind of identity:
+`TypeIdentifier` is the identity of a fully constructed type. It is an abstract base with three concrete subtypes, each representing a different kind of identity:
 
 ```
-TypeId (abstract)
-├── MappedTypeId      — leaf type from a mapped assembly. Has a GUID. SQL-storable.
-├── StableNameTypeId  — type(s) entirely from stable assemblies. Untouched AssemblyQualifiedName.
-└── ConstructedTypeId — mixed: AssemblyQualifiedName with some GUID, 0 components.
+TypeIdentifier (abstract)
+├── MappedTypeIdentifier   — leaf type from a mapped assembly. Has a GUID. SQL-storable.
+├── StableNameTypeId       — type(s) entirely from stable assemblies. Untouched AssemblyQualifiedName.
+└── ConstructedTypeId      — mixed: AssemblyQualifiedName with some GUID, 0 components.
 ```
 
-All three expose a **string representation** — the `AssemblyQualifiedName`-format string used by serialization. Only `MappedTypeId` additionally exposes a **GUID** for SQL storage.
+All three expose a **string representation** — the `AssemblyQualifiedName`-format string used by serialization. Only `MappedTypeIdentifier` additionally exposes a **GUID** for SQL storage.
 
-### MappedTypeId
+### MappedTypeIdentifier
 
 A leaf type from a mapped assembly. Has an explicitly assigned GUID. String representation is `"GUID, 0"`.
 
-This is the only subtype that can be stored in SQL GUID columns. The event store, document DB, tessaging outbox/inbox, and Typermedia routing all deal in `MappedTypeId`.
+This is the only subtype that can be stored in SQL GUID columns. The event store, document DB, tessaging outbox/inbox, and Typermedia routing all deal in `MappedTypeIdentifier`.
 
 ### StableNameTypeId
 
@@ -115,15 +109,15 @@ Examples: `List<MyEntity>` → `"System.Collections.Generic.List`1[[e4a8c9f2-...
 
 Resolution requires walking the string, resolving GUID components via the mapping dictionary, and reconstructing with `Type.MakeGenericType()` / `Type.MakeArrayType()`.
 
-### TypeId is a pure identity value
+### TypeIdentifier is a pure identity value
 
-`TypeId` subtypes are dumb value objects — they hold only the string representation (and GUID for `MappedTypeId`). They do not participate in parsing or resolution. That logic lives in the `TypeNameMapper`.
+`TypeIdentifier` subtypes are dumb value objects — they hold only the string representation (and GUID for `MappedTypeIdentifier`). They do not participate in parsing or resolution. That logic lives in the `TypeNameMapper`.
 
-### Open generic mappings are NOT TypeIds
+### Open generic mappings are NOT TypeIdentifiers
 
 An open generic like `List<>` is not a type — it's a template. It never exists at runtime, never gets serialized, never gets stored, never crosses the wire. Its GUID mapping exists solely as a building block for constructing and parsing `ConstructedTypeId` strings.
 
-This mapping is represented by `OpenGenericId` — a GUID-backed struct, distinct from `TypeId`. The `ITypeMapper` may handle the `OpenGenericId` ↔ open generic `Type` mapping internally, but `OpenGenericId` is never returned where a `TypeId` is expected. TypeIds name fully constructed types; `OpenGenericId` names a template.
+This mapping is represented by `OpenGenericId` — a GUID-backed struct, distinct from `TypeIdentifier`. The `ITypeIdentifierMapper` may handle the `OpenGenericId` ↔ open generic `Type` mapping internally, but `OpenGenericId` is never returned where a `TypeIdentifier` is expected. TypeIdentifiers name fully constructed types; `OpenGenericId` names a template.
 
 ---
 
@@ -136,7 +130,7 @@ This mapping is represented by `OpenGenericId` — a GUID-backed struct, distinc
      mapper.UseStableNameStrategyForAssembliesContaining<NodaTime.Instant, SomeOtherLib.Foo>();
      ```
 
-2. **Mapped assemblies** — types that need rename-safety. Leaf types get GUID assignments (`MappedTypeId`). Open generic definitions get GUID assignments (not TypeIds — building blocks only). Registered explicitly per-container:
+2. **Mapped assemblies** — types that need rename-safety. Leaf types get GUID assignments (`MappedTypeIdentifier`). Open generic definitions get GUID assignments (not TypeIdentifiers — building blocks only). Registered explicitly per-container:
    ```csharp
    mapper.MapTypesFromAssemblyContaining<MyEntity>();
    ```
@@ -162,7 +156,7 @@ static class MyAssemblyTypeMappings : ITypeMappingDeclaration
 }
 ```
 
-`MapOpenGeneric` is a separate method from `Map` to make it explicit that open generics are not types — they are templates. This mapping produces an `OpenGenericId`, not a `TypeId`. In practice, `MapOpenGeneric` is rarely needed — most generics used in serialized data come from stable assemblies (BCL collections, etc.).
+`MapOpenGeneric` is a separate method from `Map` to make it explicit that open generics are not types — they are templates. This mapping produces an `OpenGenericId`, not a `TypeIdentifier`. In practice, `MapOpenGeneric` is rarely needed — most generics used in serialized data come from stable assemblies (BCL collections, etc.).
 
 The framework enforces that a mapping class only maps types from its own assembly. Mapping a type from another assembly is an error at registration time.
 
@@ -171,7 +165,7 @@ The framework enforces that a mapping class only maps types from its own assembl
 ## Per-container registration (no global state)
 
 ```csharp
-container.RegisterTypeMapper(mapper =>
+container.RegisterTypeIdentifierMapper(mapper =>
 {
    mapper
       .MapTypesFromAssemblyContaining<MyEntity>()
@@ -183,7 +177,7 @@ container.RegisterTypeMapper(mapper =>
 - No `AppDomain.AssemblyLoad` hook
 - No static singleton
 - No auto-discovery
-- Each container owns its `ITypeMapper` instance with its own mappings
+- Each container owns its `ITypeIdentifierMapper` instance with its own mappings
 - If a container didn't register an assembly's mappings, serializing those types is an error
 
 ---
@@ -195,8 +189,8 @@ Three separate classes, each with one job:
 1. **`TypeNameParser`** — parses a standard `AssemblyQualifiedName`-format string into a tree of `TypeName, Assembly` components with nested type arguments. Works on both Newtonsoft's raw output and our persisted form (same structure). Independently testable, separate class, no mapping knowledge.
 
 2. **`TypeNameMapper`** — walks a parsed tree and transforms it:
-   - **Serialize direction**: Given a .NET `Type`, produces a `TypeId` (choosing the correct subtype). For mapped types: replaces type name with GUID, assembly with `0`. For stable types: passes through unchanged. For composites: walks components recursively.
-   - **Deserialize direction**: Given a `TypeId`, resolves it back to a .NET `Type`. `MappedTypeId` → dictionary lookup. `StableNameTypeId` → `Type.GetType()`. `ConstructedTypeId` → parse, resolve components recursively, `MakeGenericType()` / `MakeArrayType()`.
+   - **Serialize direction**: Given a .NET `Type`, produces a `TypeIdentifier` (choosing the correct subtype). For mapped types: replaces type name with GUID, assembly with `0`. For stable types: passes through unchanged. For composites: walks components recursively.
+   - **Deserialize direction**: Given a `TypeIdentifier`, resolves it back to a .NET `Type`. `MappedTypeIdentifier` → dictionary lookup. `StableNameTypeId` → `Type.GetType()`. `ConstructedTypeId` → parse, resolve components recursively, `MakeGenericType()` / `MakeArrayType()`.
    - Caches results in both directions.
 
 3. **`RenamingDecorator`** — finds `$type` values in JSON, delegates to `TypeNameMapper`, puts the result back. Stays trivial (~20 lines).
@@ -205,7 +199,7 @@ Three separate classes, each with one job:
 
 ## SQL storage
 
-TypeId columns in the event store, document DB, tessaging, and Typermedia remain GUID columns. These accept only `MappedTypeId` — enforced at the type level. This is not a limitation in practice: events and documents are concrete leaf domain types, not generic collections.
+TypeIdentifier columns in the event store, document DB, tessaging, and Typermedia remain GUID columns. These accept only `MappedTypeIdentifier` — enforced at the type level. This is not a limitation in practice: events and documents are concrete leaf domain types, not generic collections.
 
 ---
 
@@ -220,9 +214,9 @@ TypeId columns in the event store, document DB, tessaging, and Typermedia remain
 
 ## What changes
 
-- `TypeId` — from a single GUID-backed type to an abstract base with three subtypes
-- `ITypeMapper` — becomes container-scoped, explicitly configured. Produces `MappedTypeId` for leaf types. May handle `OpenGenericId` ↔ `Type` mappings internally, but `OpenGenericId` is not a `TypeId`.
-- `TypeMapper` — no longer a static singleton
+- `TypeIdentifier` — from a single GUID-backed type to an abstract base with three subtypes
+- `ITypeIdentifierMapper` — becomes container-scoped, explicitly configured. Produces `MappedTypeIdentifier` for leaf types. May handle `OpenGenericId` ↔ `Type` mappings internally, but `OpenGenericId` is not a `TypeIdentifier`.
+- `TypeIdentifierMapper` — no longer a static singleton
 - `RenamingDecorator` — delegates structural work to `TypeNameParser` + `TypeNameMapper`
 - Generated mapping files — only contain leaf types and open generic definitions
 - Persisted `$type` strings — structural `AssemblyQualifiedName` format with GUIDs for mapped components
@@ -231,7 +225,7 @@ TypeId columns in the event store, document DB, tessaging, and Typermedia remain
 
 - Leaf types get explicit GUID assignments
 - SQL schema stays GUID-based
-- `GetType(MappedTypeId)` / `GetId(Type)` for leaf types — same dictionary lookup
+- `GetType(MappedTypeIdentifier)` / `GetId(Type)` for leaf types — same dictionary lookup
 
 ## Resolved questions
 

samples/AccountManagement/src/AccountManagement.API/TypeMappingDeclarations.cs

@@ -1,12 +1,12 @@
 using Compze.TypeIdentifiers;
 
-[assembly: TypeMappings(typeof(AccountManagement.API.TypeMappingDeclarations))]
+[assembly: AssemblyTypeMapper(typeof(AccountManagement.API.AssemblyTypeMapper))]
 
 namespace AccountManagement.API;
 
-class TypeMappingDeclarations : ITypeMappingDeclaration
+class AssemblyTypeMapper : IAssemblyTypeMapper
 {
-   public void DeclareMappings(ITypeMappingRegistrar map)
+   public void Map(ITypeMappingRegistrar map)
    {
       map.Map<AccountResource>("84c1bfcd-a5dd-41e2-ade0-e25bbe0337c3")
          .Map<AccountResource.Tommand.ChangeEmail>("337af6fe-e645-49c7-9da1-b00dbc19cfa6")

samples/AccountManagement/src/AccountManagement.Domain.Tevents/TypeMappingDeclarations.cs

@@ -1,12 +1,12 @@
 using Compze.TypeIdentifiers;
 
-[assembly: TypeMappings(typeof(AccountManagement.Domain.Tevents.TypeMappingDeclarations))]
+[assembly: AssemblyTypeMapper(typeof(AccountManagement.Domain.Tevents.AssemblyTypeMapper))]
 
 namespace AccountManagement.Domain.Tevents;
 
-class TypeMappingDeclarations : ITypeMappingDeclaration
+class AssemblyTypeMapper : IAssemblyTypeMapper
 {
-   public void DeclareMappings(ITypeMappingRegistrar map)
+   public void Map(ITypeMappingRegistrar map)
    {
       map.Map<IAccountTevent.Created>("ae1684ff-a150-4840-ac08-1b9d21806da6")
          .Map<AccountTevent.LoggedIn>("37079b83-103e-4832-a718-3ad4c71700a7")

samples/AccountManagement/src/AccountManagement.Server/TypeMappingDeclarations.cs

@@ -1,12 +1,12 @@
 using Compze.TypeIdentifiers;
 
-[assembly: TypeMappings(typeof(AccountManagement.TypeMappingDeclarations))]
+[assembly: AssemblyTypeMapper(typeof(AccountManagement.AssemblyTypeMapper))]
 
 namespace AccountManagement;
 
-class TypeMappingDeclarations : ITypeMappingDeclaration
+class AssemblyTypeMapper : IAssemblyTypeMapper
 {
-   public void DeclareMappings(ITypeMappingRegistrar map)
+   public void Map(ITypeMappingRegistrar map)
    {
       map.Map<Domain.Account>("57fc716d-d8ca-4224-9f78-4d3b5a7f9ebd")
          .Map<UI.QueryModels.AccountQueryModel>("aee890be-6bb0-4301-90d5-492b0b42a4a8")

src/Compze.Abstractions/TypeMappingDeclarations.cs

@@ -1,13 +1,13 @@
 using Compze.Abstractions.Tessaging.Public;
 using Compze.TypeIdentifiers;
 
-[assembly: TypeMappings(typeof(Compze.Abstractions.TypeMappingDeclarations))]
+[assembly: AssemblyTypeMapper(typeof(Compze.Abstractions.AssemblyTypeMapper))]
 
 namespace Compze.Abstractions;
 
-class TypeMappingDeclarations : ITypeMappingDeclaration
+class AssemblyTypeMapper : IAssemblyTypeMapper
 {
-   public void DeclareMappings(ITypeMappingRegistrar map)
+   public void Map(ITypeMappingRegistrar map)
    {
       map.Map<IExactlyOnceTevent>("0d68a831-87c0-4d05-8e52-bf063d51b56d")
          .Map<IRemotableTevent>("887aad71-52f3-46f8-a26a-e2886941758d")

src/Compze.Core/Tessaging/Internal/SqlLayer/_IServiceBusSqlLayer.cs

@@ -30,25 +30,25 @@ public enum SaveTessageResult
 
    public interface IInboxSqlLayer
    {
-      SaveTessageResult SaveTessage(TessageId tessageId, MappedTypeId typeId, string serializedTessage);
+      SaveTessageResult SaveTessage(TessageId tessageId, MappedTypeIdentifier typeId, string serializedTessage);
       int MarkAsSucceeded(TessageId tessageId);
       int RecordException(TessageId tessageId, string exceptionStackTrace, string exceptionTessage, string exceptionType);
       int MarkAsFailed(TessageId tessageId);
       Task InitAsync();
    }
 
-   public class OutboxTessageWithReceivers(string serializedTessage, MappedTypeId typeId, TessageId tessageId, IEnumerable<EndpointId> receiverEndpointIds)
+   public class OutboxTessageWithReceivers(string serializedTessage, MappedTypeIdentifier typeId, TessageId tessageId, IEnumerable<EndpointId> receiverEndpointIds)
    {
       public string SerializedTessage { get; } = serializedTessage;
-      public MappedTypeId TypeId { get; } = typeId;
+      public MappedTypeIdentifier TypeId { get; } = typeId;
       public TessageId TessageId { get; } = tessageId;
       public IEnumerable<EndpointId> ReceiverEndpointIds { get; } = receiverEndpointIds.ToList();
    }
 
-   public class UndeliveredTessage(TessageId tessageId, MappedTypeId typeId, string serializedTessage, EndpointId targetEndpointId, int retryCount, DateTime? lastAttemptTime)
+   public class UndeliveredTessage(TessageId tessageId, MappedTypeIdentifier typeId, string serializedTessage, EndpointId targetEndpointId, int retryCount, DateTime? lastAttemptTime)
    {
       public TessageId TessageId { get; } = tessageId;
-      public MappedTypeId TypeId { get; } = typeId;
+      public MappedTypeIdentifier TypeId { get; } = typeId;
       public string SerializedTessage { get; } = serializedTessage;
       public EndpointId TargetEndpointId { get; } = targetEndpointId;
       public int RetryCount { get; } = retryCount;

src/Compze.Core/Tessaging/Teventive/Internal/Implementation/TaggregateTypeValidator.cs

@@ -67,10 +67,10 @@ static IReadOnlyList<Type> GetAllInheritingClassesOrInterfaces(Type type) => typ
 {
    public static void RegisterWith(IComponentRegistrar registrar)
       => registrar.Register(Singleton.For<ITaggregateTypeValidator>()
-                                     .CreatedBy((IStructuralTypeMapper typeMapper) => new TaggregateTypeValidator(typeMapper)));
+                                     .CreatedBy((ITypeMapper typeMapper) => new TaggregateTypeValidator(typeMapper)));
 
-   readonly IStructuralTypeMapper _typeMapper;
-   TaggregateTypeValidator(IStructuralTypeMapper typeMapper) => _typeMapper = typeMapper;
+   readonly ITypeMapper _typeMapper;
+   TaggregateTypeValidator(ITypeMapper typeMapper) => _typeMapper = typeMapper;
 
    public void AssertIsValid<TTaggregate>() => ValidatorFor<TTaggregate>.AssertValid(_typeMapper);
 
@@ -79,7 +79,7 @@ static class ValidatorFor<TTaggregate>
       // ReSharper disable once StaticMemberInGenericType (This is exactly the effect we are after...)
       static bool _validated;
 
-      internal static void AssertValid(IStructuralTypeMapper typeMapper)
+      internal static void AssertValid(ITypeMapper typeMapper)
       {
          if(_validated) return;
 
@@ -88,7 +88,7 @@ internal static void AssertValid(IStructuralTypeMapper typeMapper)
          _validated = true;
       }
 
-      static void AssertValidInternal(IStructuralTypeMapper typeMapper)
+      static void AssertValidInternal(ITypeMapper typeMapper)
       {
          var classInheritanceChain = typeof(TTaggregate).ClassInheritanceChain().ToList();
          var inheritedTaggregateType = classInheritanceChain.Single(baseClass => baseClass.IsConstructedGenericType && baseClass.GetGenericTypeDefinition() == typeof(Taggregate<,,,,>));