Walkthrough: one orders app from request to response, as a sample that CI builds and runs #116

Problem

Each guide covers one boundary:

• binding and rejected input in docs/aspnet-core.md;
• the wire form in docs/json.md;
• columns and the SQL a query becomes in docs/ef-core.md;
• PATCH bodies in docs/merge-patches.md;
• logs in docs/logging-and-secrets.md.

None shows one value object crossing all of them in a single application, and none says where it changes on the way through. Its text guard cleans it in Create. It's written as the wrapped type's JSON and stored as a plain column, and .Value in a query becomes that column in SQL. A rejected value gets an answer that never quotes the input, and a masked value is masked in a log line.

The smoke test's host consumer puts EF Core and the OpenAPI document together, but it's a check, not something a reader can follow. A walkthrough written as prose alone would go stale, because nothing would run it end to end.

This is TypeKit's counterpart of CaffeinatedCoder/CodoMetis.ValueRanges#418.

Change

• A sample application that runs. A minimal API orders service, built on the Generators, EF Core, ASP.NET Core and Serilog packages:
  • value objects: an id over Guid, an e-mail address validated by Create with a text guard, a quantity, and an order status as a closed set;
  • bound from the route, the query string and a JSON body, with a rejected value answered as problem details;
  • handlers that return a Result as the HTTP response, and an Option for a missing order as a 404;
  • storage with EF Core on SQLite in memory, and a query that filters on .Value;
  • a PATCH endpoint taking a Patch<T>;
  • logging through the Serilog policy, with the e-mail address masked;
  • the OpenAPI document.
• CI runs it and checks what it says. A fifth consumer, walkthrough, in tools/ConsumerSmokeTest, asserts on the HTTP responses, the SQL EF Core logs, the log lines and the OpenAPI document, never on the exit code alone. It builds against the packed packages outside the repository, as a reader's project would, so Directory.Build.props doesn't apply. It runs on SQLite in memory like host, so it needs no container and runs on every OS leg. Native AOT stays with the aot consumer.
• docs/walkthrough.md, in the plain-docs voice, quotes excerpts from the sample and links to its full source. Each step says what changes at that boundary, or that nothing does.
• The excerpts are the sample's code. Today ReadmeSampleTests finds a page's regions only in test/CodoMetis.TypeKit.Samples. Extend it so that this page's regions (// sample: walkthrough/{name} ... // end sample) are found in the walkthrough consumer's sources, under the same exactly-one-region rule. The outputs the page states in comments (a response body, the SQL, a log line) are read from the page by the smoke test's assertions, so the page and the program can't drift apart. As everywhere else, a changed output is fixed in the comment, never in the test.
• Claims. The page's promises go into test/oracles/claims.json. If heldBy can't name the smoke consumer, an integration test holds them.

Done when

• The sample builds and runs in CI on every PR and fails when an answer it prints changes.
• docs/walkthrough.md is linked from the README's "Documentation" table and from docs/value-objects.md, and from the docs site's navigation once that exists (Docs site: publish docs/ and the READMEs to GitHub Pages from main, with API pages #115).
• Seeded and caught: an excerpt edited in the page without the sample's source fails ReadmeSampleTests, and an answer changed in the sample without the page's comment fails the smoke test.