@drunkcoding/dknet-implementation-skills 0.1.0

package/skills/dknet-dto-mapping/SKILL.md

@@ -0,0 +1,278 @@
+---
+name: dknet-dto-mapping
+description: Design response DTOs and Mapster mapping for a DKNet.Minimal feature — hand-written vs [GenerateDto] shapes, custom Mapster IRegister mappings for values the generator's convention can't produce, LazyMapper, and the JSON/sensitive-data contract. Use after (or alongside) dknet-crud when a handler needs a DTO to return.
+---
+
+# DTO and Mapster mapping
+
+Response DTO shape and how it gets filled from the entity. For request contracts, validators and
+handlers, load `dknet-crud`. For paged query projections, load `dknet-queries-specs`.
+
+## Two DTO shapes
+
+**Hand-written** — a plain record, exactly the fields you list:
+
+```csharp
+// ManualSample/V1/PurchaseOrderDto.cs
+public sealed record PurchaseOrderDto
+{
+    public Guid Id { get; init; }
+    public string CustomerName { get; init; } = null!;
+    public decimal Amount { get; init; }
+    public PurchaseOrderStatus Status { get; init; }
+    public string CreatedBy { get; init; } = null!;
+}
+```
+
+This carries **no attribute at all**, yet `mapper.Map<PurchaseOrderDto>(order)` and
+`mapper.ResultOf<PurchaseOrderDto>(order)` both work correctly. Mapster's global convention
+(`TypeAdapterConfig.GlobalSettings.Default`, configured once in `AppSetup.cs`) maps any two types by
+flexible name matching with no registration required — a hand-written DTO whose property names
+match the entity's needs nothing further.
+
+**Generated** — one attribute on an empty `partial record`:
+
+```csharp
+[GenerateDto(typeof(Product),
+    Exclude = [nameof(Product.OwnedBy), nameof(AuditedEntity<Guid>.LastModifiedBy), nameof(AuditedEntity<Guid>.LastModifiedOn)])]
+public sealed partial record ProductDto
+{
+    [SensitiveData("pricing")]
+    public decimal? GrossMargin { get; init; }
+}
+```
+
+`DKNet.EfCore.DtoGenerator` emits every remaining audited property at compile time. What that
+produces here, verbatim (`obj/Generated/DKNet.EfCore.DtoGenerator/.../ProductDto.g.cs`):
+
+```csharp
+public partial record ProductDto
+{
+    public required string Name { get; init; }
+    public decimal Price { get; init; }
+    public bool IsDiscontinued { get; init; }
+    [SensitiveData("pricing")] public decimal? SupplierCostPrice { get; init; }
+    [SensitiveData] public string? SupplierReferenceCode { get; init; }
+    [MaxLength(500)] public required string CreatedBy { get; init; }
+    public DateTimeOffset CreatedOn { get; init; }
+    [MaxLength(500)] public string? UpdatedBy { get; init; }
+    public DateTimeOffset? UpdatedOn { get; init; }
+    public Guid Id { get; init; }
+}
+```
+
+`[SensitiveData]` and `[MaxLength]` on the entity property travel onto the generated one unchanged —
+that's how `SupplierCostPrice`/`SupplierReferenceCode` stay gated per caller (see
+`docs`'s role-aware filtering, summarized below) without being declared twice. The DTO's own
+`GrossMargin` is the file's one hand-written addition, on the *other*, non-generated partial
+declaration — the generator's output file is never edited directly.
+
+## `[GenerateDto]` options
+
+```csharp
+public GenerateDtoAttribute(Type entityType)
+public string[] Exclude { get; set; } = [];          // mutually exclusive with Include
+public string[] Include { get; set; } = [];           // only these properties, if set
+public bool IgnoreComplexType { get; set; }            // default true: navigation properties dropped
+```
+
+`Include` and `Exclude` are mutually exclusive — set one or the other, never both. `Product`'s DTO
+uses `Exclude` because it wants "everything except three names"; reach for `Include` when you want
+"only these few" instead. `IgnoreComplexType` defaults to `true` (falls through to the MSBuild
+property `DtoGeneratorIgnoreComplexType` if set, else `true`): navigation properties to other
+entities are dropped automatically unless the target is `[Owned]`. Set it `false` per-DTO to include
+navigation properties.
+
+**Why `OwnedBy`, `LastModifiedBy`, `LastModifiedOn` are excluded.** `OwnedBy` duplicates
+`CreatedBy` as the same ownership key — excluding it avoids exposing the tenant key twice, and
+means it is unqueryable via the generic list route by construction (you cannot filter by ownership
+key over HTTP even though the column exists). `LastModifiedBy`/`LastModifiedOn` on
+`AuditedEntity<TKey>` are *computed* conveniences (the updated value, or the created one if never
+modified) — not mapped columns. Left on a generated DTO, they'd resolve on `GetById` (read once, in
+memory) but break the **list** route: its filter/search/order build EF predicates against the entity
+by property name, and an unmapped member makes the whole query fail to translate at the database —
+a `500`, not a `400`, the first time `?search=` touches it. `UpdatedBy`/`UpdatedOn` stay — they are
+real mapped columns covering the same intent.
+
+## Mapster global configuration
+
+`Minimal.AppServices/AppSetup.cs`, run once at startup:
+
+```csharp
+TypeAdapterConfig.GlobalSettings.Default.NameMatchingStrategy(NameMatchingStrategy.Flexible);
+TypeAdapterConfig.GlobalSettings.Default.MapToConstructor(true);
+TypeAdapterConfig.GlobalSettings.Default.PreserveReference(true);
+TypeAdapterConfig.GlobalSettings.ScanMaps();
+TypeAdapterConfig.GlobalSettings.Compile();
+
+services.AddSingleton(TypeAdapterConfig.GlobalSettings)
+        .AddScoped<IMapper, ServiceMapper>();
+```
+
+`ScanMaps()` (`Minimal.AppServices/Extensions/MapsToExtensions.cs`) reflects over the assembly for
+every type carrying `[MapsFrom(typeof(Entity))]` or `[GenerateDto(typeof(Entity))]` and calls
+`config.NewConfig(entityType, dtoType)` for each — this is what makes a generated/`[MapsFrom]`-typed
+pair eagerly compiled and validated at startup, rather than resolved lazily by the `Default`
+fallback rule on first use. **Ordering matters**: only *after* that loop does it call
+`config.Scan(assembly)`, which discovers `IRegister` classes (like `ProductMappingRegister`) and
+merges their `ForType` customizations onto the config the loop just built. Reversing the order would
+have the convention's `NewConfig` wipe out the `IRegister`'s merge.
+
+`[MapsFrom]` on a hand-written DTO (`Minimal.AppServices.Extensions.MapsFromAttribute`) is **not
+required for the mapping to work** — `PurchaseOrderDto` proves that with zero attributes and zero
+registration. Reach for it only when you also want to attach a Mapster `IRegister` customization
+(a computed property, a rename) to that specific entity/DTO pair: `[MapsFrom]` puts the hand-written
+pair through the same `ScanMaps()` → `NewConfig` → `IRegister`-merge pipeline `[GenerateDto]` already
+gets, so a custom `ForType` call has a config to merge onto instead of relying on the untyped
+`Default` fallback.
+
+## Custom response mapping
+
+A value the naming convention can't derive — anything computed from more than one column — is a
+hand-written property on the DTO's `partial record` plus an `IRegister`:
+
+```csharp
+internal sealed class ProductMappingRegister : IRegister
+{
+    public void Register(TypeAdapterConfig config) =>
+        config.ForType<Product, ProductDto>()
+            .Map(d => d.GrossMargin, s => s.Price - s.SupplierCostPrice);
+}
+```
+
+`ForType<TSource, TDest>()` **merges** onto whatever config already exists for that pair — every
+convention-mapped property (`Name`, `Price`, the audit columns) stays untouched; only `GrossMargin`
+is affected. `NewConfig` would **replace** the pair's whole config instead, silently discarding the
+convention mapping — never use `NewConfig` inside an `IRegister` meant to *add* one property.
+
+Keep the mapping expression a plain, EF-translatable expression (`s.Price - s.SupplierCostPrice`,
+not a method call or branch Entity Framework can't turn into SQL): on a generated CRUD entity, the
+list route projects the DTO directly over `IQueryable<TEntity>`, so every property's mapping
+expression must compile to SQL, not just to CLR code. A hand-mapped property is **response-only** —
+it has no entity counterpart, so the generic list route refuses to filter or order on it
+(`?orderBy=grossMargin` and `?filter=grossMargin:GreaterThan:0` both answer `400` naming the field,
+not `500` — the field-existence check catches it before a query is built). Mirror any
+`[SensitiveData]` restriction from the source columns onto the derived property if it discloses the
+same information — `GrossMargin` carries `[SensitiveData("pricing")]` because it discloses the same
+confidential number as `SupplierCostPrice`.
+
+Two tests pin this shape: `Architecture/ProductGrossMarginStructureTests.cs` asserts no hand-written
+route, request, or handler type exists anywhere with "GrossMargin" in its name — proving the
+customization stayed a mapping concern, not a routing one — and
+`Integration/AutomatedSample/V1/ProductGrossMarginTests.cs` proves the value appears correctly on
+every generated route's response (create, get, list, each `[CrudUpdate]`/`[CrudAction]`), is `null`
+(not omitted) for a caller in the required role when the source is undisclosed, is omitted entirely
+for a caller outside that role, and that ordering/filtering by it is refused with `400` while
+ordinary fields keep working.
+
+## Other customizations
+
+Still inside an `IRegister`'s `ForType<TSource, TDest>()` chain:
+
+- **Ignore a member**: `.Ignore(d => d.SomeField)` — the DTO keeps the property but Mapster never
+  writes it (default value stays). Prefer `Exclude`/`Include` on `[GenerateDto]` when the property
+  shouldn't exist on the DTO at all.
+- **Rename**: `.Map(d => d.NewName, s => s.OldName)` — same mechanism as `GrossMargin`, one column
+  instead of a computed expression; stays EF-translatable.
+- **Enums and strings**: convention mapping handles same-named enum-to-enum and enum-to-string by
+  member name already; only add a `.Map(...)` when you need a different textual representation than
+  the default.
+- **Nested/owned types**: convention mapping recurses into an owned type's own properties by name;
+  `[GenerateDto(..., IgnoreComplexType = false)]` is what lets a navigation property reach the DTO at
+  all.
+- **`AfterMapping`**: `.AfterMapping((src, dest) => ...)` runs CLR code after the projection — safe
+  for a hand-written DTO read one row at a time (`mapper.Map<TDto>(entity)`), but **not**
+  EF-translatable, so it cannot appear in a mapping used by the generic list route's `IQueryable`
+  projection. Treat any `AfterMapping` customization as reads-only, never wired to a
+  `[GenerateDto]` type that a list route also projects.
+
+## LazyMapper
+
+`DKNet.SlimBus.Extensions.LazyMapper` (namespace already in `GlobalUsings.cs`) gives two extension
+methods on `IMapper`:
+
+- `mapper.ResultOf<TDto>(entity)` — wraps `entity` in a **successful** `IResult<TDto>`, mapped only
+  when its `.Value` is first read. Use this as a handler's return value right after a write whose
+  DTO needs something only `SaveChanges` produces — a database-generated `Id`, `CreatedOn`,
+  `CreatedBy`/`OwnedBy` stamped by a save hook. Because the SlimBus EF Core interceptor runs
+  synchronously right after `OnHandle` returns and before the framework reads the `Result`'s value
+  to build the HTTP response, those values already exist by the time the lazy mapping actually runs.
+- `mapper.LazyMap<TValue>(entity)` — the same deferred mapping, without the `IResult` wrapper, for a
+  context that isn't returning a `FluentResults` result directly.
+
+For an ordinary read, or a write where nothing on the DTO depends on a post-save value (an amount
+change, a status flip), map eagerly instead: `Result.Ok(mapper.Map<TDto>(entity))`.
+
+## Paged projection
+
+```csharp
+new StaticPagedList<TDto>(page.Select(mapper.Map<TDto>), page)
+```
+
+`page` is the `IPagedList<TEntity>` from `repository.ToPagedListAsync(spec, pageIndex, pageSize, ct)`
+(`X.PagedList`); wrapping the mapped items in `StaticPagedList<TDto>` alongside the original page
+carries its paging metadata (page number, total count) forward onto the DTO-typed result.
+
+## JSON contract
+
+`Minimal.Share/SharedConsts.JsonSerializerOptions` is the one source of truth for serialization
+shape — camelCase property names, nulls omitted (`DefaultIgnoreCondition.WhenWritingNull`), enums as
+camelCase strings (`JsonStringEnumConverter(JsonNamingPolicy.CamelCase)`). `ServiceConfigs.AddOptions`
+copies these settings onto ASP.NET Core's own `JsonOptions` via `ConfigureHttpJsonOptions`, so a
+minimal-API response and this constant never drift apart. The same call site also opts the app into
+role-aware `[SensitiveData]` filtering (`UseRoleAwareSensitiveData`, needing
+`ISensitiveDataPrincipalAccessor` from DI) — the full caller/role decision table is a
+`dknet-auth-and-ownership` concern, not this skill's; what matters here is that it is response-side
+JSON serialization only, layered on top of whatever DTO shape and Mapster mapping you built, never a
+change to the DTO type itself.
+
+## Decision table
+
+| | Hand-written record | `[GenerateDto]` |
+|---|---|---|
+| Response shape | Exactly what you list | Every audited property, minus `Exclude` |
+| New entity property | Invisible until you add it | Appears automatically on next build |
+| Query surface (generated list route) | N/A — no generated list route without `[CrudCreate]`/`[GenerateDto]` together | DTO fields are the filter/search/order surface |
+| Derived/computed value | Any C# expression, `AfterMapping` included | Only via a hand-written partial member + `IRegister`, and only if EF-translatable |
+| Needs `[MapsFrom]`? | Only to attach an `IRegister` customization | N/A — `[GenerateDto]` already opts in |
+
+Pick hand-written when the response should intentionally expose less than the entity, or when a
+value needs CLR-only computation (`AfterMapping`, external lookups) and will never back a generated
+list route. Pick `[GenerateDto]` when the entity already carries `[CrudCreate]`/`[CrudUpdate]` and
+the DTO doubles as the generic CRUD/list contract.
+
+## Common mistakes
+
+- **What you might expect**: adding `NewConfig(typeof(Product), typeof(ProductDto))` inside a new
+  `IRegister` is a normal way to add one more mapping rule.
+  **What actually happens**: every property `[GenerateDto]`'s convention was already mapping for
+  that pair stops working — only what the new `NewConfig` explicitly re-declares survives.
+  **Why**: `NewConfig` replaces a pair's whole configuration; `ForType` merges onto it. Inside an
+  `IRegister` meant to add to an existing generated or `[MapsFrom]` pair, always use `ForType`.
+
+- **What you might expect**: a DTO member with no matching entity property is harmless as long as
+  it's nullable and never populated by a create/update request.
+  **What actually happens**: `GET`/`?search=` on the generic list route throws or 500s the first
+  time that field participates in a query, or (if the field genuinely doesn't exist on the entity at
+  all) the route answers `400` naming it as unsupported.
+  **Why**: list-route filter/search/order resolve DTO fields against mapped entity columns; a
+  property that's declared-but-unmapped fails to translate (500), and one with no entity
+  counterpart at all fails the existence check first (400) — see `LastModifiedBy`/`LastModifiedOn`
+  vs `GrossMargin` above for the two cases.
+
+- **What you might expect**: forgetting `partial` on a `[GenerateDto]` record is a harmless typo the
+  compiler will catch immediately with a clear message.
+  **What actually happens**: it does fail to compile, but as a "partial declarations must have
+  matching partial modifiers" error against the generator's own output file, not against your file
+  — easy to mis-diagnose as a generator bug.
+  **Why**: `[GenerateDto]` emits a second `partial record` declaration under the same name; without
+  `partial` on your declaration the two can't merge.
+
+- **What you might expect**: putting an acting-user field (`ByUser`, `CreatedBy`) on a DTO record
+  is fine since the entity already carries it.
+  **What actually happens**: it maps through unchanged on a **read**, which is fine, but on a DTO
+  used as part of a create/update request shape (rare, but seen when a hand-written request and its
+  response DTO are conflated) it becomes caller-settable.
+  **Why**: DTOs and requests are different concerns — a DTO is response-only; acting-user
+  attribution belongs on the request (`dknet-crud`) or a save hook, never inferred
+  from a response type reused as input.

package/skills/dknet-efcore-config/SKILL.md

@@ -0,0 +1,379 @@
+---
+name: dknet-efcore-config
+description: Create EF Core entity type configurations (mappers), static data seeders, CoreDbContext wiring, and infra domain-service implementations following this project's assembly-scan auto-discovery conventions. Use after creating a domain entity, for both mode=manual and mode=auto entities.
+---
+
+# Skill: EF Core Configuration
+
+Create the persistence-layer configuration for a domain entity — mapper, optional static seed data,
+and (rarely) an infra domain-service implementation. This layer is **hand-written identically for
+both entity shapes** (`dknet-entity`'s `mode=manual`/`mode=auto`): no generator in this
+template — not `[RaisesEvent]`, not `[CrudCreate]`/`[CrudUpdate]`/`[CrudAction]`, not
+`[GenerateDto]` — touches `IEntityTypeConfiguration<T>`. `ProductConfigs` (for the generator-driven
+`Product`) is exactly as hand-written as `PurchaseOrderConfigs`.
+
+## Mapper
+
+`Minimal.Infra/Features/ManualSample/Mappers/PurchaseOrderConfigs.cs` — the whole file:
+
+```csharp
+internal sealed class PurchaseOrderConfigs : DefaultEntityTypeConfiguration<PurchaseOrder>
+{
+    public override void Configure(EntityTypeBuilder<PurchaseOrder> builder)
+    {
+        base.Configure(builder);
+
+        builder.HasIndex(p => p.CustomerName);
+        builder.Property(p => p.CustomerName).HasMaxLength(200).IsRequired();
+        builder.Property(p => p.Amount).HasPrecision(18, 2);
+        builder.Property(p => p.Status).HasConversion<string>();
+        builder.ToTable("PurchaseOrders", "manual_sample");
+    }
+}
+```
+
+`Minimal.Infra/Features/AutomatedSample/Mappers/ProductConfigs.cs` — the whole file:
+
+```csharp
+internal sealed class ProductConfigs : DefaultEntityTypeConfiguration<Product>
+{
+    public override void Configure(EntityTypeBuilder<Product> builder)
+    {
+        base.Configure(builder);
+
+        builder.Property(p => p.Name).HasMaxLength(150).IsRequired();
+        builder.HasIndex(p => p.Name).IsUnique();
+        builder.Property(p => p.Price).HasPrecision(18, 2);
+        builder.Property(p => p.OwnedBy).HasMaxLength(500).IsRequired();
+        builder.Property(p => p.SupplierCostPrice).HasPrecision(18, 2);
+        builder.Property(p => p.SupplierReferenceCode).HasMaxLength(50);
+        builder.ToTable("Products", "sample");
+    }
+}
+```
+
+Location: `Minimal.Infra/Features/<Feature>/Mappers/<Entity>Configs.cs`. Discovered by
+`UseAutoConfigModel([typeof(CoreDbContext).Assembly, typeof(Sequences).Assembly])` — an **assembly
+scan for every `IEntityTypeConfiguration<T>`**, not a Scrutor convention scan (see Infra services,
+below, for what Scrutor actually is and isn't used for here). This call is wired in **both**
+`InfraSetup.AddInfraServices` and `InfraMigration.MigrateDb`.
+
+**Always call `base.Configure(builder)` first.** `DefaultEntityTypeConfiguration<TEntity>`
+(`DKNet.EfCore.Extensions`) does three things when it applies:
+
+- If an `Id` property exists: `HasKey("Id")`, plus a value generator — `ValueGeneratedOnAdd()` for a
+  numeric key, or `ValueGeneratedOnAdd().HasValueGenerator<GuidV7ValueGenerator>()` for a `Guid` key
+  (a time-ordered GUID assigned at insert, distinct from the plain `Guid.NewGuid()` an
+  `AggregateRoot(string createdBy)` constructor assigns eagerly in memory — see
+  `dknet-entity`).
+- If the entity implements `IAuditedProperties`: `CreatedBy`/`CreatedOn` required, `CreatedBy`
+  max length 255, both locked against change after insert (`SetAfterSaveBehavior`); `UpdatedBy` max
+  length 255, nullable; `UpdatedOn` nullable.
+- If the entity implements `IConcurrencyEntity<T>`: a `RowVersion` concurrency token,
+  `ValueGeneratedOnAddOrUpdate()`. Neither sample uses this.
+
+There is no soft-delete / `IsDeleted` convention anywhere in this base class or in either sample —
+don't assume one exists.
+
+Beyond `base.Configure`, everything is ordinary EF Core Fluent API: `HasIndex` (plain, or
+`.IsUnique()` for a real business constraint — `Product.Name`'s uniqueness is enforced by the
+database index, not the `CreateProductRequestValidator`, which only *checks* first — two concurrent
+callers can still both pass the check), `HasMaxLength`/`HasPrecision` on every column, and
+`ToTable("Name", "schema")` with a literal schema string or a `DomainSchemas` constant (both samples
+use a literal). Store every mapped enum with `HasConversion<string>()` —
+`InfraTests.AllEnumProperties_StoringToDb_ShouldHaveStringConversion` enforces this for every enum
+property in the model, and `PurchaseOrder.Status` is the shipped example. Give every mapped `string`
+an explicit `HasMaxLength` — `InfraTests.NoEntityString_ShouldBe_ConfiguredAs_Max` fails on any
+unconstrained string, which on PostgreSQL would otherwise map to unbounded `text`.
+
+**Owned types (`OwnsOne`/`OwnsMany`).** Not exercised by either shipped sample — no `OwnsOne` call
+exists anywhere under `ApiEndpoints`. Configure one inside the owning entity's own
+`Configure(builder)`, after `base.Configure(builder)`, the same as any other Fluent API call:
+
+```csharp
+builder.OwnsOne(e => e.ShippingAddress, owned =>
+{
+    owned.Property(p => p.Street).HasMaxLength(200).IsRequired();
+    owned.Property(p => p.City).HasMaxLength(100).IsRequired();
+});
+```
+
+There is no separate `OwnedDataContext` or similar file in this template — an owned type is
+configured where its owner is, not in a shared file.
+
+## Static data seeding
+
+`Minimal.Infra/Features/ManualSample/StaticData/PurchaseOrderStaticData.cs` — the whole file:
+
+```csharp
+internal sealed class PurchaseOrderStaticData : DataSeedingConfiguration<PurchaseOrder>
+{
+    protected override ValueTask<ICollection<PurchaseOrder>> GetDataAsync(
+        CancellationToken cancellation = new())
+    {
+        return ValueTask.FromResult<ICollection<PurchaseOrder>>(
+        [
+            new PurchaseOrder(
+                new Guid("6E6F4D3C-1B7E-4C7A-9F1D-8A2B5C6D7E01"),
+                "Acme Pte Ltd", 1250.00m, SharedConsts.SystemAccount),
+            new PurchaseOrder(
+                new Guid("6E6F4D3C-1B7E-4C7A-9F1D-8A2B5C6D7E02"),
+                "Globex Corporation", 875.50m, SharedConsts.SystemAccount),
+            new PurchaseOrder(
+                new Guid("6E6F4D3C-1B7E-4C7A-9F1D-8A2B5C6D7E03"),
+                "Initech LLC", 430.25m, SharedConsts.SystemAccount)
+        ]);
+    }
+}
+```
+
+Location: `Minimal.Infra/Features/<Feature>/StaticData/<Entity>StaticData.cs`. Inherit the
+**base class** `DataSeedingConfiguration<T>` (`DKNet.EfCore.Extensions.Configurations`) — not an
+`IDataSeedingConfiguration<T>` interface. Override the `protected` `GetDataAsync(CancellationToken)`
+and return the fixed rows via the entity's `internal` rehydration constructor (known `Guid`s,
+`SharedConsts.SystemAccount` as `createdBy`) — never the public constructor, so seeding never
+re-raises the entity's created event. Class must be `internal sealed`
+(`InfraTests.AllSeedingDataClassesShouldBeInternalAndSealed`, checked against
+`IDataSeedingConfiguration` implementers).
+
+**Re-run semantics** (from `DataSeedingConfiguration<T>`'s own doc comments): the base class's
+`GetMissingAsync` filters the rows `GetDataAsync` returns down to the ones **not already present by
+primary key** before inserting — comparing key columns read from the database, not entity equality
+(a plain reference type has no `Equals` override, so entity-equality comparison would never match
+freshly materialized rows and would re-insert every candidate on every run). This means seeding is
+**insert-if-missing only**: it inserts a row whose fixed `Guid` isn't in the table yet, and never
+updates a row that's already there, even if `GetDataAsync`'s in-code values changed since the row was
+first seeded.
+
+**Discovery and the two-call-site rule.** `UseAutoDataSeeding([typeof(InfraSetup).Assembly])` scans
+for every `IDataSeedingConfiguration` implementer by assembly scan (same style as
+`UseAutoConfigModel`, not Scrutor) and must be called in **both**:
+
+- `Minimal.Infra/Extensions/InfraSetup.cs` → `AddInfraServices` (the DI-registered `CoreDbContext`
+  the running app uses)
+- `Minimal.Infra/Extensions/InfraMigration.cs` → `MigrateDb` (a **separate** `CoreDbContext` built
+  for the startup-migration path; seeding runs as part of `db.Database.MigrateAsync()`)
+
+This is a real bug the template hit once already: `PurchaseOrderStaticData` was correctly discovered
+by the DI-path context but the migration path built its own context without the same
+`.UseAutoDataSeeding(...)` call, so seed rows never appeared in a real database even though the
+migration itself ran. When adding new seed data, verify both call sites, not just one.
+
+**No test fixture wires this.** Neither `Minimal.App.Tests`' `ApiFixture` nor
+`Minimal.App.BDDTests`' `BddApiFactory` calls `.UseAutoDataSeeding(...)` on their in-memory
+`DbContext` — that wiring exists only in the two real composition-root call sites above. Tests that
+actually exercise seeded data:
+
+- `Minimal.App.Tests/Unit/ManualSample/PurchaseOrderStaticDataTests.cs` — invokes the `protected
+  GetDataAsync` via reflection (nothing public exposes it for a direct call) and asserts the three
+  fixed rows, owned by `SharedConsts.SystemAccount`, with distinct `Id`s.
+- `Minimal.App.Tests/Integration/ManualSample/V1/InfraMigrationSeedingTests.cs` — runs
+  `InfraMigration.MigrateDb` itself against a real, ephemeral Postgres `Testcontainers` instance,
+  then reads `/v1/purchase-orders` over HTTP. This is the one test that fails if
+  `.UseAutoDataSeeding(...)` is ever removed from `InfraMigration.MigrateDb`.
+
+## `CoreDbContext`
+
+`Minimal.Infra/Contexts/CoreDbContext.cs` — `internal class CoreDbContext(DbContextOptions options,
+IEnumerable<IDataOwnerProvider>? dataKeyProviders = null) : DbContext(options), IDataOwnerDbContext`.
+No `DbSet<T>` declarations anywhere — the model is built entirely from the `IEntityTypeConfiguration<T>`
+scan. It exposes `AccessibleKeys` from the first registered `IDataOwnerProvider`
+(`DKNet.EfCore.DataAuthorization` uses this for the global read filter on any `IOwnedBy` entity), and
+overrides every `SaveChanges`/`SaveChangesAsync` entry point to call `EnsureOwnershipResolvable()`
+first:
+
+```csharp
+private void EnsureOwnershipResolvable()
+{
+    if (_dataKeyProvider is null) return;
+    if (!string.IsNullOrEmpty(_dataKeyProvider.GetOwnershipKey())) return;
+
+    var hasUnattributableInsert = ChangeTracker.Entries()
+        .Any(e => e.State == EntityState.Added
+                  && e.Entity is IAuditedProperties { CreatedBy: null or "" }
+                  && e.Metadata.FindProperty(nameof(IAuditedProperties.CreatedBy)) is { IsNullable: false });
+
+    if (hasUnattributableInsert) throw new OwnershipRequiredException();
+}
+```
+
+Fails closed, before EF Core attempts the insert, when the ownership key can't be resolved and a new
+row would be left with no `CreatedBy` — otherwise EF Core's own required-property check throws a raw
+`DbUpdateException` that leaks column/entity names into the response. Mapped to `403 Forbidden` by
+the `StatusCode` branch of `AddErrorResponses(...)` (see `dknet-endpoint`), not `500`.
+
+`InfraSetup.AddInfraServices` — the DI wiring, in full:
+
+```csharp
+public static IServiceCollection AddInfraServices(this IServiceCollection service)
+{
+    service
+        .AddScoped<IMembershipService, MembershipService>()
+        .AddSpecRepo<CoreDbContext>()
+        .AddEventPublisher<CoreDbContext, EventPublisher>()
+        .AddDbContextWithHook<CoreDbContext>((sp, builder) =>
+        {
+            var config = sp.GetRequiredService<IConfiguration>();
+            var conn = config.GetConnectionString(SharedConsts.DbConnectionString)!;
+
+            builder.UseNpgsqlWithMigration(conn)
+                .UseAutoConfigModel([typeof(CoreDbContext).Assembly, typeof(Sequences).Assembly])
+                .UseAutoDataSeeding([typeof(InfraSetup).Assembly]);
+        });
+
+    return service;
+}
+
+internal static DbContextOptionsBuilder UseNpgsqlWithMigration(
+    this DbContextOptionsBuilder builder, string connectionString) =>
+    builder.UseNpgsql(connectionString, o => o
+        .MinBatchSize(1)
+        .MaxBatchSize(100)
+        .MigrationsHistoryTable(nameof(CoreDbContext), DomainSchemas.Migration)   // table "CoreDbContext", schema "migrate"
+        .MigrationsAssembly(typeof(CoreDbContext).Assembly)
+        .EnableRetryOnFailure()
+        .UseQuerySplittingBehavior(QuerySplittingBehavior.SplitQuery));
+```
+
+`Minimal.Infra/Extensions/InfraMigration.cs` — the startup-migration path, in full:
+
+```csharp
+public static async Task MigrateDb(string connectionString)
+{
+    await using var db = new CoreDbContext(
+        new DbContextOptionsBuilder<CoreDbContext>()
+            .UseAutoConfigModel([typeof(CoreDbContext).Assembly, typeof(Sequences).Assembly])
+            .UseNpgsqlWithMigration(connectionString)
+            .UseAutoDataSeeding([typeof(InfraSetup).Assembly])
+            .Options);
+
+    // Seeding runs as part of MigrateAsync via UseAutoDataSeeding above.
+    await db.Database.MigrateAsync();
+}
+```
+
+`AddSpecRepo<CoreDbContext>()` wires `IRepositorySpec` (see `dknet-queries-specs`).
+`AddEventPublisher<CoreDbContext, EventPublisher>()` wires `Minimal.Infra/Services/EventPublisher.cs`
+— a `DefaultEventPublisher` override that does `bus.Publish(eventObj)` — as the sink both raise
+styles (`AddEvent`/`[RaisesEvent]`) publish through after a successful save.
+
+## Migrations
+
+Always from the solution's `ApiEndpoints/` directory (there is no wrapper script — inline the real
+`dotnet ef` command):
+
+```bash
+dotnet ef migrations add <Name> -c CoreDbContext -p Minimal.Infra/Minimal.Infra.csproj
+dotnet ef migrations remove -c CoreDbContext -p Minimal.Infra/Minimal.Infra.csproj
+```
+
+Inspect the generated migration under `Minimal.Infra/Migrations/` before continuing — confirm the
+table, columns, and any index/constraint match what the mapper declares. Never edit an
+already-applied migration; add a new one instead. `Architecture/MigrationSchemaTests.cs` pins
+specific facts about the compiled model: `Product.Name` has a **unique** single-column index,
+the model declares a sequence in schema `seq` and a sequence named `Seq_Membership` (never one named
+after `Sequences.None`), the provider is not SQL Server, and both `Minimal.AppHost` and
+`Minimal.Infra` reference PostgreSQL/Npgsql packages, never SQL Server ones. At application start,
+`FeatureManagement:RunDbMigrationWhenAppStart` (or the `migration` launch argument — `dotnet run
+--project ApiEndpoints/Minimal.Api -- migration`) is what actually calls this path; removing a
+feature's tables is a **drop migration**, covered by `dknet-feature-lifecycle`, not here.
+
+## Infra domain services
+
+`Minimal.Domains/Services/` holds the interface, `Minimal.Infra/Services/` the implementation,
+`InfraSetup.AddInfraServices` the registration — **by explicit `AddScoped<TInterface,
+TImplementation>()`, one line per service.** There is no Scrutor convention scan anywhere in this
+template's `Minimal.Infra` registration path — the only `Scan(` call in the whole solution is
+Mapster's `TypeAdapterConfig.Scan` in `Minimal.AppServices/Extensions/MapsToExtensions.cs`, unrelated
+to service registration. Do not rely on a naming convention or namespace
+(`.Services`/`.Repos`) to get a service registered — add the `AddScoped` line yourself. `internal
+sealed` is still required by the same architecture rule that covers mappers/handlers/validators
+whenever the class implements a handler-shaped interface (`InfraTests.AllHandlerClassesShouldBeInternalAndSealed`
+covers `IRequestHandler<>`/`IConsumer<>` implementers specifically — a plain domain-service
+implementation like `MembershipService` isn't targeted by that rule either, but follow the same
+`internal sealed` convention regardless).
+
+```csharp
+// Minimal.Infra/Services/SequenceService.cs — internal abstract base, one per sequence-backed service
+internal abstract class SequenceService(DbContext dbContext, Sequences sequence) : ISequenceServices
+{
+    public virtual async ValueTask<string> NextValueAsync() =>
+        dbContext.IsNpgsql()
+            ? await dbContext.NextSeqValueWithFormat(sequence)
+            : Guid.NewGuid().ToString();
+}
+
+// Minimal.Infra/Services/MembershipService.cs — the whole file
+internal sealed class MembershipService(CoreDbContext dbContext)
+    : SequenceService(dbContext, Sequences.Membership), IMembershipService;
+```
+
+`NextValueAsync()` formats the next value with the sequence's `FormatString` on PostgreSQL
+(`NextSeqValueWithFormat`), and falls back to a plain `Guid` when the context isn't Npgsql — so a
+unit test against an in-memory/SQLite context never needs a real Postgres sequence. Add your own
+service the same way: an interface in `Minimal.Domains/Services/`, an `internal sealed`
+implementation in `Minimal.Infra/Services/`, one `AddScoped` line in `AddInfraServices`.
+
+## Architecture tests constraining `Minimal.Infra`
+
+`Architecture/InfraTests.cs`:
+
+- `AllEfConfigClassesShouldBeInternalAndSealed` — every `IEntityTypeConfiguration<T>` implementer.
+- `AllSeedingDataClassesShouldBeInternalAndSealed` — every `IDataSeedingConfiguration` implementer.
+- `AllHandlerClassesShouldBeInternalAndSealed` — every `IRequestHandler<>`/`IRequestHandler<,>`/
+  `IConsumer<>` implementer (covers `Minimal.Infra/Features/*/ExternalEvents/*` consumers).
+- `AllValidatorClassesShouldBeInternalAndSealed` — every `AbstractValidator<T>` subclass found in
+  `Minimal.Infra` (none shipped there today; validators live in `Minimal.AppServices`).
+- `AllEnumProperties_StoringToDb_ShouldHaveStringConversion` — every enum property in the built
+  model must have `ProviderClrType == typeof(string)`.
+- `NoEntityString_ShouldBe_ConfiguredAs_Max` — every mapped `string` property must have an explicit
+  `MaxLength` and a non-`(max)` column type.
+- `DesignTimeServiceProvider_CanActivateEventPublisher` — `dotnet ef`'s design-time service provider
+  must be able to resolve `IEventPublisher`/`IMessageBus`; guards a real regression where
+  `dotnet ef database update` died mid-seed because the design-time provider had no bus registered.
+
+## Step-by-step
+
+1. Create `Minimal.Infra/Features/<Feature>/Mappers/<Entity>Configs.cs`: `internal sealed class
+   <Entity>Configs : DefaultEntityTypeConfiguration<Entity>`, call `base.Configure(builder)` first,
+   then indexes, `HasMaxLength`/`HasPrecision` on every column, `HasConversion<string>()` on every
+   enum, `ToTable("<Plural>", "<schema>")`.
+2. If the feature needs reference data, create `Minimal.Infra/Features/<Feature>/StaticData/<Entity>StaticData.cs`:
+   `internal sealed class <Entity>StaticData : DataSeedingConfiguration<Entity>`, override
+   `GetDataAsync`, build rows via the entity's `internal` rehydration constructor with fixed `Guid`s
+   and `SharedConsts.SystemAccount`.
+3. If the feature needs a new domain service, add the interface under `Minimal.Domains/Services/`,
+   an `internal sealed` implementation under `Minimal.Infra/Services/`, and one `AddScoped<...>()`
+   line in `InfraSetup.AddInfraServices`.
+4. Generate and inspect the migration from `ApiEndpoints/`:
+   `dotnet ef migrations add <Name> -c CoreDbContext -p Minimal.Infra/Minimal.Infra.csproj`.
+5. `dotnet build -c Release` and `dotnet test --settings coverage.runsettings` from the solution
+   root.
+
+## Validation checklist
+
+- [ ] Mapper inherits `DefaultEntityTypeConfiguration<TEntity>` and calls `base.Configure(builder)` first
+- [ ] Mapper class is `internal sealed`, under `Minimal.Infra/Features/<Feature>/Mappers/`
+- [ ] Every mapped `string` has an explicit `HasMaxLength`; every mapped enum has `HasConversion<string>()`
+- [ ] A real business uniqueness needs `.IsUnique()` on the index, not just a validator check
+- [ ] `ToTable("Name", "schema")` set — literal string or a `DomainSchemas` constant
+- [ ] If seeding: class is `internal sealed`, extends `DataSeedingConfiguration<T>` (not an
+      interface), uses the entity's rehydration constructor, and `UseAutoDataSeeding(...)` is
+      present in **both** `InfraSetup.AddInfraServices` and `InfraMigration.MigrateDb`
+- [ ] If adding a domain service: interface in `Minimal.Domains/Services/`, `internal sealed`
+      implementation in `Minimal.Infra/Services/`, explicit `AddScoped<...>()` line added — no
+      convention scan will pick it up on its own
+- [ ] Migration generated from `ApiEndpoints/` and inspected before continuing
+- [ ] `dotnet build -c Release` passes
+
+## Common mistakes
+
+| Mistake | Fix |
+|---|---|
+| Expecting a namespace like `.Services`/`.Repos` to auto-register an infra service | There's no Scrutor scan for this in the template — add the explicit `AddScoped<TInterface, TImplementation>()` line in `InfraSetup.AddInfraServices` yourself. |
+| Wiring `UseAutoDataSeeding`/`UseAutoConfigModel` into only `InfraSetup.AddInfraServices` | Also wire it into `InfraMigration.MigrateDb` — that path builds its own `CoreDbContext`; seed data silently never appears over HTTP otherwise. Real bug this template already hit once. |
+| Expecting re-running seeding to update a changed fixed row | `DataSeedingConfiguration<T>` only inserts rows missing by primary key; it never updates an existing row. Change the fixed data via a migration, not by editing `GetDataAsync` and re-running. |
+| Seeding via the entity's public constructor | Use the `internal` rehydration constructor — the public one re-raises the entity's created event, which a seed insert should never do. |
+| Assuming `[SensitiveData]`/`[Range]`/etc. need mapper configuration | They don't — those are entity/DTO-level concerns (`dknet-entity`, `dknet-crud`). The mapper only configures storage shape. |
+| Forgetting `.Property(p => p.OwnedBy).HasMaxLength(...).IsRequired()` on an `IOwnedBy` entity | Implementing the interface doesn't size or require the column — `ProductConfigs` configures it explicitly. |
+| Editing an already-applied migration file by hand | Add a new migration instead; the applied one is a record of what ran against real databases. |