Release v4.0.0-preview-3

[chullybun]

Summary

Publishes v4.0.0-preview-3. All milestone work is already on main; this branch adds a final documentation/instructions clarification pass and bumps Version.props to 4.0.0-preview-3 (commit 27d729f).

Milestone

v4.0.0-preview-3 milestone — 5/5 closed.

#	Title	Type
#171	Refactor QueryArgsConfig into reusable per-entity classes, add query AI-enablement docs	PR (merged)
#172	feat: add CoreEx.Data.GraphQL (GraphQL-lite) query bridge	PR (merged)
#173	Add omitted Shopping tests to CI filters	PR (merged)
#174	Modernize ref-data querying, fix alias resolution, add coreex-graphql skill	PR (merged)
#175	JsonElementStringConverter: non-generic IConverter overloads use swapped/wrong casts	Issue (fixed by #177)

Two additional PRs merged into main in this same cycle, not tagged to the milestone but part of this release's scope:

• #176 — Add support for JSON database columns backed by non-string .NET types
• #177 — Fix JsonElementStringConverter non-generic IConverter swapped casts (closes JsonElementStringConverter: non-generic IConverter overloads use swapped/wrong casts #175)

Testing summary (AI-assisted validation)

Every PR in this cycle was built/validated through iterative AI-agent review before merge, not just a single pass — #172 in particular went through "several rounds of independent/automated review" that caught real bugs (culture-sensitive float parsing, silent long→int overflow, duplicate alias last-wins bugs, a pre-existing unrelated JsonFilter prefix-matching bug, etc.) before merge. Aggregate results reported across the individual PRs:

• CoreEx.Test.Unit: 705–735/735 passing (net8.0 / net9.0 / net10.0) depending on PR baseline; full suite green on main.
• CoreEx.Data.Test.Unit: 120/120 passing (net8.0 / net9.0 / net10.0).
• CoreEx.Data.GraphQL.Test.Unit: 118/118 passing (net8.0 / net9.0 / net10.0).
• Contoso.Products.Test.Api GraphQL-lite integration tests: 7/7 passing, including spec-compliant introspection.
• Contoso.Shopping.Test.Unit / Contoso.Shopping.Test.Subscribe: 48/48 and 15/15 passing, now restored to CI solution filters (Add omitted Shopping tests to CI filters #173).
• Real, pre-existing production bugs were found via this AI-assisted review process itself (JsonElementStringConverter: non-generic IConverter overloads use swapped/wrong casts #175/Fix JsonElementStringConverter non-generic IConverter swapped casts (#175) #177, and the JsonFilter prefix bug inside feat: add CoreEx.Data.GraphQL (GraphQL-lite) query bridge #172) rather than only via pre-written specs — i.e. the AI review loop was exercised as a genuine defect-finding pass, not rubber-stamping.
• CoreEx.sln full solution build: 0 errors, 0 warnings, all target frameworks.
• Note: integration tests requiring live SQL Server/Postgres/Service Bus infrastructure (Add support for JSON database columns backed by non-string .NET types #176) were not run in the CI/dev-loop environment and are called out for a follow-up run against local containers before final tag/publish.

This branch's own change (27d729f)

Documentation/instruction clarifications discovered while doing the above AI-assisted work, folded back into the AI workflow assets so future sessions don't repeat the same mistakes:

• Standardized GraphQL argument handling (args.GetIdentifier<TId>()) across samples/instructions.
• Documented the named cancellationToken requirement for repository paging methods (prevents parameter-binding errors).
• Clarified ref-data field naming (navigation property, not {Name}Code).
• Added a CQRS read service/controller scaffolding gate requiring repository query methods first.
• Warned against inventing CoreEx API member names; added a resolution order.
• Bumped Version.props to 4.0.0-preview-3.

Co-authored-by: Copilot App 223556219+Copilot@users.noreply.github.com

[Copilot]

Pull request overview

Publishes v4.0.0-preview-3 by bumping the shared version and applying a final clarification pass across the CoreEx docs/AI guidance (GraphQL-lite usage, query/paging conventions, CQRS scaffolding gates, and docs-sync guardrails).

Changes:

• Bump Version.props to 4.0.0-preview-3.
• Clarify/query sample patterns (notably GraphQL-lite identifier handling and named cancellationToken for paging helpers).
• Tighten AI skill/instruction guidance (CQRS read-service gating, ref-data field naming, “don’t invent API member names”, docs-sync restart reminder).

Reviewed changes

Copilot reviewed 21 out of 21 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
Version.props	Version bump to 4.0.0-preview-3.
src/CoreEx.EntityFrameworkCore/AGENTS.md	EF Core usage guide updates (CRUD + mapped model + paging/query sample).
src/CoreEx.Data/AGENTS.md	Query/paging sample updated to include paging + named cancellationToken.
src/CoreEx.Data.GraphQL/README.md	GraphQL-lite docs updated to use GetIdentifier<TId>() in AddGet.
src/CoreEx.Data.GraphQL/AGENTS.md	GraphQL-lite AI usage guide aligned with GetIdentifier<TId>().
samples/docs/hosts-layer.md	Sample host docs aligned with current GraphQL-lite root registration pattern.
docs/capabilities.md	Capabilities docs aligned with current GraphQL-lite registration guidance.
.github/skills/coreex-repository/SKILL.md	Repository skill clarifications (ref-data nav property naming; named cancellationToken).
.github/skills/coreex-repository/references/workflow.md	Repository workflow guidance expanded (ref-data field rule; named cancellationToken).
.github/skills/coreex-graphql/SKILL.md	GraphQL skill guidance tightened (identifier arg handling; usage rules).
.github/skills/coreex-graphql/references/workflow.md	GraphQL workflow examples updated to GetIdentifier<TId>().
.github/skills/coreex-docs-sync/SKILL.md	Docs-sync skill clarifies reporting + client restart when skill set changes.
.github/skills/coreex-docs-sync/README.md	Docs-sync README adds restart note after skill add/remove/rename.
.github/skills/coreex-app-service/SKILL.md	App-service skill adds CQRS gating: require repo query methods first.
.github/skills/coreex-app-service/references/workflow.md	App-service workflow adds “stop-and-check” CQRS guidance.
.github/skills/coreex-api/SKILL.md	API skill adds CQRS gating: create read service before read controllers.
.github/skills/coreex-api/references/workflow.md	API workflow adds explicit “do not skip” read-service gate.
.github/instructions/coreex-repositories.instructions.md	Repository instruction clarifications (named token; ref-data field naming; mapper call patterns).
.github/instructions/coreex-host-setup.instructions.md	Host setup instructions updated for GraphQL-lite guidance.
.github/instructions/coreex-conventions.instructions.md	Conventions expanded (named token guidance; “don’t invent member names” resolution order).
.github/copilot-instructions.md	Adds CPM note about spike/reflection projects inside the repo tree.

Suppressed comments (1)

.github/skills/coreex-graphql/references/workflow.md:65

• GetIdentifier validates presence and type (cast) but does not perform type conversion; the comment currently implies conversion.

 // GetIdentifier<TId> reads/converts the named argument (default "id") and throws an ArgumentException, mapped by the engine to ARGUMENT_ERROR, if missing/empty/wrong-typed.
 .AddGet<{Entity}>("{entity}", (args, ct) => CoreEx.ExecutionContext.GetRequiredService<I{Entity}ReadService>().GetAsync(args.GetIdentifier<string>(), ct));

[Copilot]

Pull request overview

Copilot reviewed 21 out of 21 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 22 out of 22 changed files in this pull request and generated no new comments.

Suppressed comments (2)

.github/skills/coreex-graphql/SKILL.md:54

• name = "id" is not valid C# named-argument syntax (it should be name: "id"). As written, this example won’t compile if someone copies it verbatim.

- Use `args.GetIdentifier<TId>(name = "id")` inside an `AddGet<T>` resolver to validate the identifier argument's presence and type (it casts to `TId`, it does not convert) — it throws an `ArgumentException` (mapped to `ARGUMENT_ERROR`) if missing/empty/wrong-typed. Do not reach for `args.TryGetValue(...)` directly — `GraphQLLiteArgs` is not a dictionary; use `args.Arguments.TryGetValue(...)` only for non-identifier arguments.

src/CoreEx.Data.GraphQL/README.md:92

• This README correctly states that GetIdentifier<TId> casts (doesn’t convert). However, the API XML docs on GraphQLLiteArgs.GetIdentifier<TId> currently say it “converts”/“convertible”, which contradicts this guidance and can confuse consumers reading IntelliSense. Consider updating src/CoreEx.Data.GraphQL/GraphQLLiteArgs.cs to match the actual behavior (cast-only).

     // GetIdentifier<TId> validates the named argument (default "id") for presence and type (it casts to TId, it does not convert) and throws an ArgumentException - mapped by the engine to an ARGUMENT_ERROR GraphQL error - if
     // it is missing, empty, or the wrong type, instead of an unhandled KeyNotFoundException/NullReferenceException surfacing as an opaque EXECUTION_ERROR.
     .AddGet<Product>("product", (args, ct) => CoreEx.ExecutionContext.GetRequiredService<IProductReadService>().GetAsync(args.GetIdentifier<string>(), ct));