You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 22ac63b
Browse filesBrowse the repository at this point in the historyBrowse files
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.
|**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.
Copy file name to clipboardExpand all lines: docs/v3.0.0/ADRs/README.md
+1Lines changed: 1 addition & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -42,3 +42,4 @@ Every ADR is **Proposed** until the v3 architecture review. "Traces" lists the [
42
42
|[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 |
43
43
|[ADR-028](ADR-028-postgresql-payload-columns-and-adapter-refinements.md)| PostgreSQL payload columns are `json`, plus adapter refinements | Accepted |
44
44
|[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 |
0 commit comments