Emit exact inherited .NET member type-use facts

[woksin]

Learning

DotNetTypeUseFacts.Emit(...) currently emits members declared directly on the supplied type. Existing CritterStack concept binding and Marten document discovery traverse inherited public readable properties. Atomic adapter migration cannot safely drop those members, duplicate aggregate property lists, or reintroduce facade-local Roslyn binding.

Scope

• Add an additive .NET helper/API for an exact ordered inherited member surface.
• Define override, hiding, duplicate normalized-name and declaration-order semantics.
• Preserve exact terminal subjects and nested optional/collection shape.
• Emit unique producer-scoped member declaration/type-use/role facts suitable for atomic admission.

Non-goals

• Guessing concepts or identifiers from names/types.
• Rewriting complete ArtifactFact.Properties to bind one use.
• Framework-specific Marten/Wolverine behavior.

Acceptance criteria

• Inherited public readable properties are emitted exactly once in deterministic order.
• Overrides/hiding/case-normalized collisions have explicit deterministic conflict behavior.
• Exact subjects and nested shape survive across net8/net9/net10.
• Generated-only/non-authoritative declarations cannot originate member facts.
• Reversed source/project/member order is byte-identical.
• Existing direct-member API remains source/binary compatible.
• CritterStack Add complete bounded source evidence helpers #44 preserves inherited concept/document binding without local Roslyn rewrites.

Related: #19, Cratis/Screenplay.CritterStack#44.

[cratis-stagehand]

Investigation

Tree is clean — both throwaway probe specs removed.

What I found

Reproduced (this is a feature gap, not a bug, but I confirmed the gap with a real run). A throwaway spec against DotNetTypeUseFacts.Emit with Customer : DocumentBase (base declares Id, Name; derived declares override Name, Email) emitted member declarations name, email only — the inherited id is gone. DotNetTypeShapes.PublicReadablePropertiesOf (Source/DotNET/Generation.DotNet/DotNetTypeShapes.cs:88) uses type.GetMembers(), which is declared-members-only.

I then probed Roslyn behavior for every semantic the issue asks to define, and mapped the downstream pipeline and the CritterStack consumer. Three findings materially constrain the design:

1. Dedup is mandatory, not a preference. FactIdFor (DotNetTypeUseFacts.cs:83) encodes adapter + family + artifact subject + artifact kind + raw source name + normalized name. For an override, base and derived both have raw name Name → byte-identical FactId → DuplicateFactId in AdapterContributionAdmissionValidator.cs:193 → the entire contribution is rejected. A naive "walk and emit everything" breaks atomic admission outright.
2. DeclarationOrder must agree with the aggregate ArtifactFact.Properties list. GranularArtifactResolver.ApplyMembers seeds orders from the legacy positional index and unions granular orders; >1 distinct order for one member ⇒ GEN0050 and the artifact is omitted (GranularArtifactResolver.cs:157-168, 361-364). So an inherited Emit is unusable unless a matching inherited PropertiesOf exists for the aggregate.
3. CritterStack traverses derived-first. Both ConceptTypeReferenceBinder.PropertiesOf and MartenDocumentFacts.DocumentPropertiesOf walk BaseType derived-first, dedup on the raw ordinal name (derived wins), no case-collision handling, no authored/generated filter.

Roslyn probe results (all verified by running): covariant override keeps the derived type; generic base Generic<string>.Value substitutes to string and keeps its declaring syntax refs; metadata-base members (List<string>.Capacity/Count) have DeclaringSyntaxReferences.Length == 0; generated-only declarations are distinguishable via DotNetGeneratedSource.IsGenerated; EqualityContract and explicit interface impls are already filtered by the existing accessibility predicate.

SUGGESTED-MODEL: opus

Plan — #48

Settled (verified by running code; do not redo)

• The gap is real and is exactly PublicReadablePropertiesOf using type.GetMembers().
• Base + override produce identical FactIds. Emitting both fails admission. Emit-once is forced.
• DeclarationOrder must be a contiguous 0..n-1 over the same surface used for ArtifactFact.Properties, or GEN0050 omits the artifact.
• Case-normalized collisions (URL vs uRL) already have defined behavior end to end: distinct FactIds, same ArtifactMemberKey, downstream conflict + fail-closed. Covered by for_DotNetTypeUseFacts/when_source_property_names_normalize_to_the_same_member.cs and Generation.Specs/.../when_source_members_normalize_to_the_same_name.cs. No new mechanism needed — only extend coverage to the cross-level case.
• The authority predicate below was validated against generic bases, metadata bases, and .g.cs bases:

  property.OriginalDefinition.DeclaringSyntaxReferences.Any(reference =>
      !DotNetGeneratedSource.IsGenerated(reference.SyntaxTree) &&
      context.Projects.Any(project => project.AuthoredSyntaxTrees.Contains(reference.SyntaxTree)))

  Use .OriginalDefinition — it is what makes substituted generic members resolve.
• This filter is also what makes acceptance criterion 3 (net8/net9/net10) true: it is the mechanism that stops BCL base members, which differ per TFM, from entering the surface.

Implementation

1. Source/DotNET/Generation.DotNet/DotNetTypeShapes.cs

Add a scope enum and the inherited surface:

public enum DotNetMemberSurfaceScope { Declared = 0, Inherited = 1 }

• internal static IReadOnlyList<IPropertySymbol> InheritedPublicReadablePropertiesOf(INamedTypeSymbol type, DotNetAnalysisContext context):
  1. Walk type → BaseType, stopping before SpecialType.System_Object. Walk the constructed BaseType (not OriginalDefinition) so generic substitution is preserved.
  2. Per level, apply the existing predicate from PublicReadablePropertiesOf verbatim, plus the authority filter above.
  3. Order within a level by the existing SourceOrder then ordinal name.
  4. Concatenate derived-first, dedup on IPropertySymbol.Name with StringComparer.Ordinal, first occurrence wins.
• Public overloads mirroring the existing pair:
  PropertiesOf(INamedTypeSymbol type, DotNetAnalysisContext context, DotNetMemberSurfaceScope scope).

Note: SourceOrder's int.MaxValue fallback for metadata symbols becomes dead in this path — after the authority filter every member has a source location, which is why ordering is well-defined.

2. Source/DotNET/Generation.DotNet/DotNetTypeUseFacts.cs

Add one overload; do not touch the existing one (baseline 0.16.0 package validation):

public static IReadOnlyList<GenerationFact> Emit(
    INamedTypeSymbol type,
    ArtifactKey artifact,
    DotNetAnalysisContext context,
    Evidence evidence,
    DotNetMemberSurfaceScope scope,
    Func<IPropertySymbol, ArtifactMemberRoleKind?>? roleFor = null)

Overload resolution is safe: the existing overload's 5th parameter is optional, the new one's is required, so Emit(t, a, c, e) and Emit(t, a, c, e, lambda) both still bind to the existing method. Factor the loop body so both overloads share it; the only difference is the member list. DeclarationOrder stays the loop index over the resolved surface. Evidence stays the caller's single use-site evidence (anchored at the derived type) — that is what keeps source-authority validation passing for cross-project bases.

3. Semantics to document explicitly (acceptance criterion 2)

Case	Behavior
override	Most-derived declaration only. Covariant override keeps the derived type.
new / hiding	Most-derived declaration only; base is dropped.
Base member hidden by a non-public-readable derived new	Base declaration survives (matches CritterStack today). Document it.
Two raw names normalizing to one member (any level)	Both emitted, distinct FactIds, same ArtifactMemberKey → existing downstream conflict + fail-closed.
Metadata-only / generated-only / non-authored declaration	Never originates a member fact; silently excluded (Emit has no diagnostic channel — adapters own diagnostics).
Interfaces	Out of scope for v1: base-class chain only. BaseType is null for interfaces, and AllInterfaces has no source-deterministic order. No current consumer needs it. State this as a documented limitation.

Ordering: derived-first. This is a deliberate choice to match MartenDocumentFacts.DocumentPropertiesOf and ConceptTypeReferenceBinder.PropertiesOf, so CritterStack#44's "compatibility wrapper produces byte-identical output" criterion holds. Base-first would be a more natural reading of "declaration order" but would reorder every inherited Marten document artifact in the printed .play.

4. Specs — Source/DotNET/Generation.DotNet.Specs/for_DotNetTypeUseFacts/

Follow given.a_compilation; one Because(), one assertion per [Fact].

• when_emitting_inherited_member_facts.cs — derived-first order, contiguous DeclarationOrder, exact terminal subject and nested Optional|Collection|Named shape preserved on an inherited member.
• when_a_member_is_overridden.cs — one declaration; covariant override keeps the derived type; assert FactIds are distinct (this is the admission-breaking case).
• when_a_member_is_hidden.cs — new wins, one fact.
• when_inherited_source_property_names_normalize_to_the_same_member.cs — base URL + derived uRL, both retained, AdapterContributionAdmission.Admit succeeds.
• when_a_base_declaration_is_generated.cs and when_a_base_type_comes_from_metadata.cs — no facts originate.
• when_a_base_type_is_generic.cs — substituted terminal type.
• when_emitting_inherited_members_from_projects_in_reversed_order.cs — copy the projector pattern from for_DotNetSourceStructures/when_creating/from_projects_in_reversed_order.cs; cross-project base type, forward vs reversed DotNetAnalysisContext, byte-identical projection.
• for_DotNetTypeShapes/when_reading_the_inherited_property_surface.cs — the PropertiesOf(..., Inherited) overload, asserting order identity with the fact surface (this pairing is what prevents GEN0050).

5. Docs and verification

• Documentation/guides/build-source-adapter.md (~lines 356-360): document the scope overload, the derived-first rule, the override/hiding/collision table, the interface limitation, and — most important — the pairing rule: an adapter using Inherited for Emit must use Inherited for ArtifactFact.Definition.Properties too, or GEN0050 omits the artifact.
• README.md: add a capability-table row (e.g. "Exact inherited .NET member type-use fact emission | No | Yes") and extend the paragraph at line 156.
• scripts/verify-package-consumers.sh: extend the ExternalCustomerAdapter scenario (~line 1889) with an inherited event base so the packaged surface is exercised.

Verify

dotnet test Screenplay.Generation.slnx --configuration Debug
dotnet build Screenplay.Generation.slnx --configuration Release   # multi-TFM + package baseline validation
./scripts/verify-package-consumers.sh

Needs a human decision

1. Derived-first vs base-first. I recommend derived-first for the byte-identical reason above, and the plan assumes it. Worth one line of confirmation from the reporter since it is the one choice that is expensive to reverse later.
2. The authority filter is a deliberate behavior divergence from CritterStack. CritterStack's helpers today include metadata base members; acceptance criteria 3 and 4 require excluding them. Any Marten document whose base class lives in a referenced assembly will lose those members. This is the intended improvement, but it means CritterStack#44's "byte-identical" criterion holds for source-declared bases only. The implementer should pack this branch locally and run the CritterStack specs before closing Add complete bounded source evidence helpers #44.

Suggested model for implementation: opus

---

Posted by Stagehand (AI) - an autonomous agent, not a person. Review accordingly.