Skip to content

Report what an application says about how it is served - #2422

Closed
woksin wants to merge 3 commits into
mainfrom
feat/screenplay-report-transport-concerns
Closed

Report what an application says about how it is served#2422
woksin wants to merge 3 commits into
mainfrom
feat/screenplay-report-transport-concerns

Conversation

@woksin

@woksin woksin commented Jul 29, 2026

Copy link
Copy Markdown
Contributor

Added

woksin and others added 3 commits July 29, 2026 15:51
Chronicle tags observers, read models and event types alike, and only the
event had somewhere to put them - so the reading lived where the event was
read. Nothing about it is particular to events.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VRa2Z1cA6D3Fuw9TAo6m2p
The generator reports everything it cannot express, so that a reader can tell
an application that does not do something from a generator that could not say
it. Three things broke that and were passed over without a word: a query the
host pages or sorts, a route template declared with [Path], [Route] or on an
HTTP verb, and the tags a read model carries - while an event's tags are
printed, which makes their absence read like the application's own.

Paging, sorting and routes share SP0041: all three say how a caller reaches
the application rather than what it is, so a reader who does not want to hear
about it suppresses one code. Tags take SP0042, because the reason differs -
a read model is named in the document only as what a query answers with, so
what it carries beyond its shape has nowhere to go at all.

The plumbing a host fills in of its own - a cancellation token, a query
context - is still passed over silently. Neither says anything about the
application.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VRa2Z1cA6D3Fuw9TAo6m2p
@woksin woksin added the patch label Jul 29, 2026
@woksin

woksin commented Jul 29, 2026

Copy link
Copy Markdown
Contributor Author

Reviewer context — deliberately kept out of the description.

This is agent-authored and no human has read it yet. Green CI is not sign-off.

Closes the three silent drops in #2415. Codes are allocated in one range from this branch alone: SP0041 and SP0042, above the previous high of SP0040, with SP0029 still the deliberate gap.

One code or three

The issue left this open. Paging, sorting and route templates share SP0041: all three say how a caller reaches the application rather than what it is, and a reader who does not want to hear about how the application is served wants to suppress all of it at once. Tags take SP0042 because the reason is different — a read model is named in the document only as what a query answers with, so what it carries beyond its shape has nowhere to go at all. That is also why tags read as the more surprising omission: an event's tags are printed, so their absence on read models reads like the application's own.

Both are Information, so neither changes an exit code.

Verified against source MSBuild compiles

Ada declares none of these — no query takes Paging or Sorting, no [Path], no tagged read model, no controllers (the four Paging/Sorting matches in its source are specs constructing a QueryContext). Its document is unchanged at 9,486 lines with an identical code profile, which answers the volume question in the issue for that application: zero.

So the behaviour was exercised on a purpose-built application compiled through MSBuild, not only on source strings — a read model that is tagged, routed with [Path], and paged and sorted, plus a controller with [Route] and a verb template:

Before After
diagnostics SP0012 x1 SP0012 x1, SP0041 x6, SP0042 x1
document 26 lines, reads back clean 26 lines, reads back clean
SP0042 [Library.Authors.Listing] The read model 'Author' is tagged 'audit', 'catalog', and a read model is named in the document only as what a query answers with, so it has nowhere to carry them
SP0041 [Library.Authors.Listing] The read model 'Author' is served at '/catalog/authors' rather than the conventional route, which Screenplay has no counterpart for
SP0041 [Library.Authors.Listing] The query 'AuthorsByName' is served with paging, which says how the result is asked for rather than what it is, and Screenplay has no counterpart for it
SP0041 [Library.Authors.Listing] The query 'AuthorsByName' is served with sorting, …
SP0041 [Library.Authors.Listing] The query 'AuthorsByName' is served at '/catalog/authors/by-name' …
SP0041 [Library.Authors.Registration] The controller 'RegistrationsController' is served at 'catalog/registrations' …
SP0041 [Library.Authors.Registration] The command 'RegisterAuthor' is served at 'register-author' …

A bare [HttpGet] with no template says nothing, which is what the last row of that table is meant to show.

Judgment calls worth checking

  • What stays silent. A cancellation token and a QueryContext are still passed over without a word. Neither says anything about the application, so reporting them would be noise in exactly the place this change exists to keep readable.
  • A controller command is named as the document names it — after its request type (RegisterAuthor), not after the method (Register). A message naming something the document does not contain would be worse than no message.
  • Tags.Of was lifted out of EventReader first, as its own commit, so the behaviour commit reads as behaviour. Nothing about reading tags was ever particular to events.

Verification

Release 0/0 on Screenplay, Screenplay.Specs and Screenplay.EndToEnd; 1,150 specs pass (four new, one rewritten — a_query_the_host_hands_more_than_arguments asserted should_report_nothing, which was the contract violation written down as an assertion). markdownlint clean on the changed page. The 14 broken documentation links verify-links.sh reports on this branch are pre-existing and are what #2421 fixes; none of them are in the page changed here.

@woksin

woksin commented Jul 29, 2026

Copy link
Copy Markdown
Contributor Author

CI note — the red check here is not a defect in this branch.

Two separate non-results stacked on run 30458066898:

  1. A transient Yarn install resolution failureYN0082: @swc/core-darwin-arm64@npm:1.15.47: No candidates found. That version does exist on npm, and yarn.lock is gitignored in this repository, so every run resolves fresh and is exposed to registry propagation. A run on another branch got past the same step minutes later, and so did the re-run here.
  2. Cancellation. .NET Build shares a concurrency group across pull requests targeting main, so the newest run cancels the others and a cancelled run reports as a failure. On the re-run, dotnet-build itself succeeded — the solution built with analyzers as errors — and 34 of the parallel spec shards were cancelled when another branch pushed.

I have not re-run again, because doing so cancels that branch's in-progress build while its author is iterating. This needs one maintainer re-run at merge time.

What stands on its own meanwhile: Release build 0 warnings / 0 errors on Screenplay, Screenplay.Specs and Screenplay.EndToEnd; 1,150 specs pass; and the end-to-end harness reads its own output back clean on both applications it was run against.

@woksin

woksin commented Jul 30, 2026

Copy link
Copy Markdown
Contributor Author

Consolidated into #2425 so the open work ships as one release. Every commit from this branch is contained in combined/one-release — nothing is lost, and the branch is left in place.

@woksin woksin closed this Jul 30, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant