The generator's stated contract is that nothing is dropped silently — everything it cannot express emits a located SP00xx diagnostic, so a reader can tell the difference between "the application does not do this" and "the generator could not say it".
Three things break that contract today. They are dropped with no diagnostic at all:
- Query paging and sorting.
a_query_the_host_hands_more_than_arguments.cs asserts should_report_nothing.
- Custom route templates. A command or query with an explicit route has it dropped without a word.
- Read model tags. Note event tags are recovered and printed, so a reader seeing tags on events could reasonably conclude a read model simply has none.
This was found while correcting Documentation/generating-a-screenplay.md, which asserted "Each is reported as a diagnostic when encountered" for the whole table — an assertion that was not true for these three rows. The documentation is now accurate, but the accurate statement is that the generator has silent drops, which is the thing the contract exists to prevent.
Why it matters
A silent drop is worse than a loud one in a document whose only value is describing the real application. A reader has no way to know the question was even asked. Two of the defects found before this package shipped were exactly this shape — an event property named Tag silently absorbed, and authorize/produces collisions silently swallowing a property — and both were fixed by making them report.
Suggested direction
Report each at Information severity where the construct is recognised but has no counterpart:
- paging and sorting: the document describes the model, not how it is served, so this is a genuine non-counterpart rather than a gap in reading
- custom routes: same
- read model tags: worth distinguishing, since a read model has no declaration of its own in the document — it appears only as the type a query returns — so this may be better framed as "the read model itself is not declared" than as a dropped tag
Whether these deserve one shared code or three is a judgment call. A single code covering "a transport or storage concern the document does not describe" may be more useful to suppress on than three.
Acceptance
Each of the three emits a located diagnostic; specs cover all three; the counts on a real application are reported so the volume is known before it ships (read model tags in particular could be numerous).
The generator's stated contract is that nothing is dropped silently — everything it cannot express emits a located
SP00xxdiagnostic, so a reader can tell the difference between "the application does not do this" and "the generator could not say it".Three things break that contract today. They are dropped with no diagnostic at all:
a_query_the_host_hands_more_than_arguments.csassertsshould_report_nothing.This was found while correcting
Documentation/generating-a-screenplay.md, which asserted "Each is reported as a diagnostic when encountered" for the whole table — an assertion that was not true for these three rows. The documentation is now accurate, but the accurate statement is that the generator has silent drops, which is the thing the contract exists to prevent.Why it matters
A silent drop is worse than a loud one in a document whose only value is describing the real application. A reader has no way to know the question was even asked. Two of the defects found before this package shipped were exactly this shape — an event property named
Tagsilently absorbed, andauthorize/producescollisions silently swallowing a property — and both were fixed by making them report.Suggested direction
Report each at Information severity where the construct is recognised but has no counterpart:
Whether these deserve one shared code or three is a judgment call. A single code covering "a transport or storage concern the document does not describe" may be more useful to suppress on than three.
Acceptance
Each of the three emits a located diagnostic; specs cover all three; the counts on a real application are reported so the volume is known before it ships (read model tags in particular could be numerous).