Skip to content

Commit 22ac63b

Browse files
committed
feat(WP-1.13): domain queries, typed builder and query-side analyzers
- [DomainQuery] named, versioned queries: the generator emits IDomainQueryRuntime (name, version, text, parameters, result columns, typed Materialize through DomainQueryValues) and registers them with the module; IQueryService.ExecuteAsync runs them in-process; the host binds every domain query against the catalog at startup (ADR-030). - Contract surface in the SourceFlow namespace (IQueryRow, DomainQueryValues) so domain code stays within ARCH-04. - Typed builder: IQueryService.Events<TEvent>() and ReadModel<TDoc>() translate a restricted expression subset into SFQL with every value as a parameter (no IQueryable, no expression compilation). - Analyzers SF0015 (query side in aggregates, process managers and projections), SF0016 (in command handlers), SF0018 (domain query shape and parameters). - Generated Guid id converters accept any Guid format. - Bank sample: accounts.low-balance domain query. - Tests GEN-47..50, UT-QL-90..95.
1 parent 0a71adf commit 22ac63b

26 files changed

Lines changed: 1606 additions & 13 deletions
Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# ADR-030: Domain queries are checked in two stages: shape at build time, binding at startup
2+
3+
| | |
4+
|---|---|
5+
| **Status** | Accepted |
6+
| **Date** | 2026-11-11 |
7+
| **Deciders** | v3 architecture review; WP-1.13 implementation |
8+
| **Amends** | [doc 14](../14-Query-Side-and-SFQL.md) Q-B4 ("the generator binds every `[DomainQuery]` at build time against the catalog") |
9+
10+
## Context
11+
12+
Doc 14 says analyzer SF0018 binds each `[DomainQuery]` against the catalog at build time, so a broken contract fails compilation. That needs two things the compiler doesn't have:
13+
14+
- **The SFQL parser and binder.** They live in `SourceFlow.Net` (`net10.0`). Analyzers and generators load into the compiler as `netstandard2.0` assemblies (ADR-004, ADR-027), so they can't reference them.
15+
- **The service's catalog.** It is built from the runtime model (ADR-029): every module the host adds, the serializer's naming policy, and its converters. A domain query in a module assembly is often bound against read models from other modules that the analyzer can't see.
16+
17+
## Decision
18+
19+
1. **SF0018 at build time** checks what the compilation can decide on its own, and reports an error when:
20+
- the attribute has no name;
21+
- the type doesn't implement `IDomainQuery<TResult>`;
22+
- the type isn't a top-level partial record or class;
23+
- there is no `const string Sfql` (or `Sql`);
24+
- the result has no public constructor with parameters;
25+
- an `@parameter` in the text, outside string literals, has no matching member.
26+
2. **Binding at startup.** `SourceFlowHost` binds every registered domain query against the service's own catalog before it reports ready, using the real parser and binder. It checks three things:
27+
- the text binds (SFQ01xx/02xx diagnostics with positions);
28+
- every bound parameter is a member;
29+
- every result constructor parameter is an output column (matched case-insensitively).
30+
31+
Any failure stops startup with `DomainQueryException`, whose message starts with "SF0018". A broken contract therefore fails the first test or deployment that starts the host, not the first caller.
32+
3. **Generated runtime.** The generator emits `IDomainQueryRuntime<TQuery, TResult>`:
33+
- the name, version, text and syntax;
34+
- the parameters (camelCase member names);
35+
- the result columns;
36+
- `ToParameters()`;
37+
- a typed `Materialize(QueryRow)` that converts through `DomainQueryValues`. Ids are recognised by `[StronglyTypedId]`, because the id interface comes from the same generator run.
38+
39+
The module registers each query (`AddDomainQuery<TQuery, TResult>()`), and `IQueryService.ExecuteAsync(query)` runs it in-process.
40+
41+
## Consequences
42+
43+
- Some contract errors (unknown read model, missing output column) surface at host startup instead of compilation. A plain host start in a unit test catches them, as UT-QL-92 does.
44+
- The analyzer stays small and fast, with no copy of the grammar.

‎docs/v3.0.0/ADRs/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,3 +42,4 @@ Every ADR is **Proposed** until the v3 architecture review. "Traces" lists the [
4242
| [ADR-027](ADR-027-single-core-package-with-extensibility-spis-and-categorised-adapters.md) | Single core package with extensibility SPIs, and categorised adapter packages | Accepted |
4343
| [ADR-028](ADR-028-postgresql-payload-columns-and-adapter-refinements.md) | PostgreSQL payload columns are `json`, plus adapter refinements | Accepted |
4444
| [ADR-029](ADR-029-schema-catalog-derived-from-serializer-metadata.md) | The schema catalog is derived at startup from the serializer's source-generated metadata | Accepted |
45+
| [ADR-030](ADR-030-domain-queries-bind-at-startup.md) | Domain queries are checked in two stages: shape at build time, binding at startup | Accepted |

‎docs/v3.0.0/implementation/STATUS.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ Updated in the PR that completes a work package (CONTRIBUTING.md). Status values
2121
| WP-1.10 | Hosting, roles, tenancy context | 1.5 | done | AddSourceFlow, SourceFlowBuilder Use* slots, roles, SourceFlowHost lifecycle, health check |
2222
| WP-1.11 | `SourceFlow.Testing` | 2.5 | done | SourceFlowTestHost, AggregateSpec, ProcessManagerSpec, ProjectionSpec, approvals; UT-TST |
2323
| WP-1.12 | Schema catalog | 2 | done | JSON Schema 2020-12 per message type and version, read-model document and process state, derived from the serializer's JsonTypeInfo with `x-sourceflow-*` extensions (ADR-029); canonical text + SHA-256 fingerprints; `ISchemaStore` (in-memory, PostgreSQL `schemas`) registered at startup, a changed published `(type, version)` fails startup (`SchemaRegistration` = Enforce/Warn/Off); lock file; `SchemaCompatibility` rules SFC01–SFC10; AsyncAPI 3.0 exporter. UT-CAT-01..18 |
24-
| WP-1.13 | SFQL front end (pipeline + SQL syntax) + in-memory interpreter + domain queries | 5.5 | in progress | Done: request guard, lexer, both parsers into one AST (UT-QL-01..13, 61..65, 69..77); catalog from the runtime model (Q-B1), binder with per-version renames, typing, output naming, G-6 tie-break, G-10/G-11/G-12 (SFQ0201–0206; UT-QL-21..33, 79, 88); policy: permissions, PII keys, cost guard, join and offset rules, limits (SFQ0301, 0401, 0402, 0405, 0406, 0409, 0501; UT-QL-34..39, 80, 89); in-memory interpreter (SQL three-valued logic, hash joins, grouping, subqueries, aggregate as-of folds, schema rows) and `IQueryService` (typed parameters SFQ0202/0203, PII redaction, tenancy, keyset continuation tokens SFQ0601, `at_least` consistency waits SFQ0602, plan cache, `IQueryEngine` SPI for provider compilers; UT-QL-41..60). PostgreSQL compiler: WP-2.8. Next: the typed builder and `[DomainQuery]` |
24+
| WP-1.13 | SFQL front end (pipeline + SQL syntax) + in-memory interpreter + domain queries | 5.5 | done | Request guard, lexer, both parsers into one AST; catalog, binder, policy (SFQ0101–0602); in-memory interpreter and `IQueryService` (typed parameters, PII redaction, tenancy, keyset continuation, `at_least` waits, plan cache, `IQueryEngine` SPI); named domain queries (`[DomainQuery]`, generated runtime, `ExecuteAsync`, startup binding, ADR-030); typed builder (`Events<T>()`, `ReadModel<T>()`); analyzers SF0015/SF0016/SF0018. UT-QL-01..95, GEN-47..50; PostgreSQL compiler in WP-2.8 |
2525
| WP-1.14 | Bank sample (ported v2 E2E domain) | 1.5 | done | Bank.Contracts/Accounts/Transfers/Notifications + E2E-01..07, 11, 13, 14, 17..20 green; Bank.Api host (commands, demo query endpoints), Studio demo console, docker-compose demo and ghcr.io images (`v3-images` workflow) |
2626
| WP-1.R | Retire v2 core | 0.5 | todo | |
2727
| WP-2.1 | PostgreSQL schema and migrator | 1.5 | done | V001 schema (ADR-028: json payload columns, tenant columns), PostgreSqlSchemaMigrator (advisory lock, checksummed schema_history, db script), UsePostgreSql with AutoMigrate (Development only by default); SCK-M01..M06. V002 (RLS) and V003 (partitioned events) come with WP-2.6 and WP-4.5 |

‎samples/Bank/Bank.Accounts/AccountSummary.cs‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,29 @@ private static AccountSummary When(AccountOpened e, AccountSummary? current, Eve
3232
}
3333
}
3434

35+
/// <summary>
36+
/// Accounts below a balance: a named, versioned domain query (doc 14 Q-B4), the stable contract other services and UIs
37+
/// use instead of ad-hoc queries.
38+
/// </summary>
39+
/// <param name="Below">The balance threshold.</param>
40+
[DomainQuery("accounts.low-balance", 1)]
41+
public sealed partial record LowBalanceAccounts(decimal Below) : IDomainQuery<LowBalanceAccount>
42+
{
43+
/// <summary>The query text.</summary>
44+
public const string Sfql = """
45+
from readmodel "account-summary"
46+
| where status = 1 and balance < @below
47+
| project accountId = id, holder, balance
48+
| order by balance
49+
""";
50+
}
51+
52+
/// <summary>A row of <see cref="LowBalanceAccounts"/>.</summary>
53+
/// <param name="AccountId">The account.</param>
54+
/// <param name="Holder">The holder.</param>
55+
/// <param name="Balance">The balance.</param>
56+
public sealed record LowBalanceAccount(AccountId AccountId, string Holder, decimal Balance);
57+
3558
/// <summary>Maps domain events to the public contract (doc 03 §7).</summary>
3659
public static class AccountContracts
3760
{

‎src/Core/SourceFlow.Generators/AnalyzerReleases.Unshipped.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,3 +13,6 @@ SF0008 | SourceFlow.Shape | Error | Aggregate or process manager shape
1313
SF0009 | SourceFlow.Purity | Warning | Non-deterministic API in a pure method
1414
SF0010 | SourceFlow.Serialization | Error | Type missing from the module's JSON context
1515
SF0014 | SourceFlow.Commands | Error | Command is both owned and routed
16+
SF0015 | SourceFlow.Query | Error | The query side is used in write-model code
17+
SF0016 | SourceFlow.Query | Warning | A command handler reads through the query side
18+
SF0018 | SourceFlow.Query | Error | Domain query is not valid

‎src/Core/SourceFlow.Generators/Diagnostics.cs‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,21 @@ internal static class Diagnostics
3737
"Command '{0}' is handled in this service by '{1}' and also routed to an endpoint; a command is owned or routed, never both (ADR-007)",
3838
"SourceFlow.Commands", DiagnosticSeverity.Error, isEnabledByDefault: true, helpLinkUri: HelpBase);
3939

40+
public static readonly DiagnosticDescriptor QueryInWriteModel = new(
41+
"SF0015", "The query side is used in write-model code",
42+
"'{0}' uses {1}; Decide, When, React and projections get state only from their own stream (Q-R1)",
43+
"SourceFlow.Query", DiagnosticSeverity.Error, isEnabledByDefault: true, helpLinkUri: HelpBase);
44+
45+
public static readonly DiagnosticDescriptor QueryInCommandHandler = new(
46+
"SF0016", "A command handler reads through the query side",
47+
"'{0}' uses {1}: decisions based on eventually consistent reads (Q-R1)",
48+
"SourceFlow.Query", DiagnosticSeverity.Warning, isEnabledByDefault: true, helpLinkUri: HelpBase);
49+
50+
public static readonly DiagnosticDescriptor DomainQueryShape = new(
51+
"SF0018", "Domain query is not valid",
52+
"Domain query '{0}': {1}",
53+
"SourceFlow.Query", DiagnosticSeverity.Error, isEnabledByDefault: true, helpLinkUri: HelpBase);
54+
4055
public static readonly DiagnosticDescriptor NoOwner = new(
4156
"SF0006", "Command has no Decide or handler",
4257
"Command '{0}' targets '{1}' but has no Decide method and no ICommandHandler in this compilation; add one or route it (startup fails otherwise)",

‎src/Core/SourceFlow.Generators/Emitters.cs‎

Lines changed: 45 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -85,7 +85,7 @@ public static string Id(IdModel model)
8585
{
8686
IdBackingKind.Int64 => "new(reader.GetInt64())",
8787
IdBackingKind.String => $"Parse(reader.GetString() ?? throw new global::System.Text.Json.JsonException(\"{self} cannot be null.\"))",
88-
_ => "new(reader.GetGuid())",
88+
_ => "reader.TryGetGuid(out global::System.Guid guid) ? new(guid) : Parse(reader.GetString() ?? throw new global::System.Text.Json.JsonException(\"" + self + " cannot be null.\"))",
8989
};
9090
string write = model.Backing == IdBackingKind.Int64 ? "writer.WriteNumberValue(value.Value);" : "writer.WriteStringValue(value.ToString());";
9191
w.Line($"public override {self} Read(ref global::System.Text.Json.Utf8JsonReader reader, global::System.Type typeToConvert, global::System.Text.Json.JsonSerializerOptions options) => {read};");
@@ -292,6 +292,43 @@ public static string SessionProjection(SessionProjectionModel model)
292292
return w.ToString();
293293
}
294294

295+
public static string DomainQuery(DomainQueryModel model)
296+
{
297+
var w = new SourceWriter();
298+
w.OpenNamespace(model.Namespace);
299+
string self = model.Name;
300+
string contract = $"{Sf}IDomainQueryRuntime<{self}, {model.ResultType}>";
301+
w.Open($"partial {model.Keyword} {self} : {contract}");
302+
w.Line($"private static readonly {Sf}DomainQueryParameter[] __sourceFlowParameters = [{string.Join(", ", model.Parameters.Select(p => $"new({Literal.Of(p.Name)}, typeof({p.Type}))"))}];");
303+
w.Line($"private static readonly string[] __sourceFlowResultColumns = [{string.Join(", ", model.Results.Select(r => Literal.Of(r.Name)))}];");
304+
w.Line($"static string {contract}.QueryName => {Literal.Of(model.QueryName)};");
305+
w.Line($"static int {contract}.QueryVersion => {model.Version.ToString(CultureInfo.InvariantCulture)};");
306+
w.Line($"static string {contract}.QueryText => {model.TextMember};");
307+
w.Line($"static bool {contract}.IsSql => {(model.IsSql ? "true" : "false")};");
308+
w.Line($"static global::System.Collections.Generic.IReadOnlyList<{Sf}DomainQueryParameter> {contract}.QueryParameters => __sourceFlowParameters;");
309+
w.Line($"static global::System.Collections.Generic.IReadOnlyList<string> {contract}.ResultColumns => __sourceFlowResultColumns;");
310+
w.Line();
311+
w.Open($"global::System.Collections.Generic.IReadOnlyDictionary<string, object?> {contract}.ToParameters()");
312+
w.Line("return new global::System.Collections.Generic.Dictionary<string, object?>(global::System.StringComparer.Ordinal)");
313+
w.Line("{");
314+
foreach (QueryParameterModel p in model.Parameters)
315+
{
316+
w.Line($" [{Literal.Of(p.Name)}] = {p.Member},");
317+
}
318+
319+
w.Line("};");
320+
w.Close();
321+
w.Line();
322+
w.Open($"static {model.ResultType} {contract}.Materialize({Sf}IQueryRow row)");
323+
string args = string.Join(", ", model.Results.Select(r =>
324+
string.Format(CultureInfo.InvariantCulture, r.Converter, $"{Sf}DomainQueryValues.Column(row, {Literal.Of(r.Name)})")));
325+
w.Line($"return new {model.ResultType}({args});");
326+
w.Close();
327+
w.Close();
328+
w.CloseNamespace(model.Namespace);
329+
return w.ToString();
330+
}
331+
295332
public static string Module(
296333
ModuleModel module,
297334
ImmutableArray<IdModel> ids,
@@ -300,7 +337,8 @@ public static string Module(
300337
ImmutableArray<ProcessManagerModel> processes,
301338
ImmutableArray<ProjectionModel> projections,
302339
ImmutableArray<SessionProjectionModel> sessionProjections,
303-
ImmutableArray<HandlerModel> handlers)
340+
ImmutableArray<HandlerModel> handlers,
341+
ImmutableArray<DomainQueryModel> domainQueries)
304342
{
305343
var w = new SourceWriter();
306344
w.OpenNamespace(module.Namespace);
@@ -346,6 +384,11 @@ public static string Module(
346384
w.Line($"builder.AddCommandHandler<{h.FullName}, {h.First}, {h.Second}>();");
347385
}
348386

387+
foreach (DomainQueryModel q in domainQueries.OrderBy(q => q.FullName, System.StringComparer.Ordinal))
388+
{
389+
w.Line($"builder.AddDomainQuery<{q.FullName}, {q.ResultType}>();");
390+
}
391+
349392
foreach (ProcessManagerModel p in processes.OrderBy(p => p.FullName, System.StringComparer.Ordinal))
350393
{
351394
w.Line($"builder.AddProcessManager<{p.FullName}, {p.IdType}>();");

‎src/Core/SourceFlow.Generators/Infrastructure.cs‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -122,6 +122,10 @@ internal static class KnownNames
122122
public const string ReactionContext = "SourceFlow.ReactionContext`1";
123123
public const string EventContext = "SourceFlow.EventContext";
124124
public const string CommandRejected = "SourceFlow.CommandRejected`1";
125+
public const string DomainQueryAttribute = "SourceFlow.DomainQueryAttribute";
126+
public const string DomainQuery = "SourceFlow.IDomainQuery`1";
127+
public const string QueryService = "SourceFlow.Query.IQueryService";
128+
public const string AggregateReader = "SourceFlow.Query.IAggregateReader";
125129
}
126130

127131
internal static class SymbolExtensions

‎src/Core/SourceFlow.Generators/ModelBuilder.cs‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -218,6 +218,100 @@ private static IEnumerable<MemberModel> Members(INamedTypeSymbol type)
218218
rejections.Distinct().OrderBy(x => x.LogicalName, System.StringComparer.Ordinal).ToEquatableArray());
219219
}
220220

221+
public static DomainQueryModel? DomainQuery(GeneratorAttributeSyntaxContext context, CancellationToken cancellationToken)
222+
{
223+
if (context.TargetSymbol is not INamedTypeSymbol type || type.IsNested() || type.IsValueType || type.IsAbstract || !type.IsPartial()
224+
|| type.FindInterface(KnownNames.DomainQuery) is not { } contract
225+
|| contract.TypeArguments[0] is not INamedTypeSymbol result)
226+
{
227+
return null;
228+
}
229+
230+
cancellationToken.ThrowIfCancellationRequested();
231+
AttributeData attribute = context.Attributes[0];
232+
if (attribute.ConstructorArguments.Length == 0 || attribute.ConstructorArguments[0].Value is not string queryName)
233+
{
234+
return null;
235+
}
236+
237+
int version = attribute.ConstructorArguments.Length > 1 && attribute.ConstructorArguments[1].Value is int v ? v : 1;
238+
IFieldSymbol? text = type.GetMembers().OfType<IFieldSymbol>()
239+
.FirstOrDefault(f => f.IsConst && f.Type.SpecialType == SpecialType.System_String && (f.Name == "Sfql" || f.Name == "Sql"));
240+
if (text is null)
241+
{
242+
return null;
243+
}
244+
245+
var parameters = new List<QueryParameterModel>();
246+
foreach (IPropertySymbol property in type.GetMembers().OfType<IPropertySymbol>())
247+
{
248+
if (property.IsStatic || property.DeclaredAccessibility != Accessibility.Public || property.Name == "EqualityContract" || property.IsIndexer)
249+
{
250+
continue;
251+
}
252+
253+
parameters.Add(new QueryParameterModel(property.Name, Camel(property.Name), property.Type.FullName()));
254+
}
255+
256+
IMethodSymbol? constructor = result.InstanceConstructors
257+
.Where(c => c.DeclaredAccessibility == Accessibility.Public)
258+
.OrderByDescending(c => c.Parameters.Length)
259+
.FirstOrDefault();
260+
if (constructor is null)
261+
{
262+
return null;
263+
}
264+
265+
var results = new List<QueryResultModel>();
266+
foreach (IParameterSymbol parameter in constructor.Parameters)
267+
{
268+
results.Add(new QueryResultModel(parameter.Name, Converter(parameter.Type)));
269+
}
270+
271+
return new DomainQueryModel(
272+
type.Namespace(), type.Name, type.FullName(), type.Keyword(), queryName, version, result.FullName(), text.Name, text.Name == "Sql",
273+
parameters.ToEquatableArray(), results.ToEquatableArray());
274+
}
275+
276+
// The DomainQueryValues call that converts a column value to a result member's type; {0} is the value expression.
277+
private static string Converter(ITypeSymbol type)
278+
{
279+
const string Values = "global::SourceFlow.DomainQueryValues";
280+
if (type is INamedTypeSymbol { OriginalDefinition.SpecialType: SpecialType.System_Nullable_T } nullable)
281+
{
282+
ITypeSymbol inner = nullable.TypeArguments[0];
283+
if (IsStronglyTypedId(inner))
284+
{
285+
return $"{Values}.NullableId<{inner.FullName()}>({{0}})";
286+
}
287+
288+
if (inner.TypeKind == TypeKind.Enum)
289+
{
290+
return $"{Values}.NullableEnum<{inner.FullName()}>({{0}})";
291+
}
292+
293+
return $"{Values}.Get<{type.FullName()}>({{0}})";
294+
}
295+
296+
if (IsStronglyTypedId(type))
297+
{
298+
return $"{Values}.Id<{type.FullName()}>({{0}})";
299+
}
300+
301+
if (type.TypeKind == TypeKind.Enum)
302+
{
303+
return $"{Values}.Enum<{type.FullName()}>({{0}})";
304+
}
305+
306+
bool reference = !type.IsValueType && type.NullableAnnotation != NullableAnnotation.Annotated;
307+
return $"{Values}.Get<{type.FullName()}>({{0}})" + (reference ? "!" : string.Empty);
308+
}
309+
310+
private static string Camel(string name)
311+
{
312+
return name.Length == 0 ? name : char.ToLowerInvariant(name[0]) + name.Substring(1);
313+
}
314+
221315
public static SessionProjectionModel? SessionProjection(GeneratorAttributeSyntaxContext context, CancellationToken cancellationToken)
222316
{
223317
if (context.TargetSymbol is not INamedTypeSymbol type || type.IsNested() || type.IsValueType || type.IsAbstract || !type.IsPartial())

0 commit comments

Comments
 (0)