[L03.01.02.01.08] Content-serialization registry + OnError hook — Web.Serialization + Web.ErrorHandling

[dotnetcadet]

Summary

Implements the re-scoped #864 (2026-07-10 owner decision): the two pipeline seams that succeeded the withdrawn IResult abstraction, delivered as two new Web feature libraries. The Web area stays middleware-first — no result carriers, no Results/TypedResults factories, handlers write responses imperatively.

1. Assimalign.Cohesion.Web.Serialization — the content-serialization registry. Media-type-keyed request-deserialization / response-serialization halves (IHttpContentReader / IHttpContentWriter, deliberately not one god ISerializer), exposed per exchange as IHttpContentSerializationFeature. Builder-time registration per the issue's shape — builder.AddJsonSerialization(AppJsonContext.Default) registers the built-in JSON pair over a source-generated IJsonTypeInfoResolver — and typed call sites request.ReadContentAsync<T>() / response.WriteContentAsync(value) with zero reflection under NativeAOT (JsonTypeInfo-based STJ entry points only, MakeReadOnly() frozen options, no reflection fallback: uncovered types fault instead).
2. Assimalign.Cohesion.Web.ErrorHandling — the OnError hook. builder.AddErrorHandling().OnError(...) registers IHttpErrorHandlers consulted in registration order; the first to return true owns the fault; when all pass, the terminal default renders the RFC 9457 Web.ProblemDetails payload via WriteProblemDetailsAsync (500, application/problem+json, about:blank, no exception detail leaked). Exposed per exchange as IHttpErrorHandlingFeature.HandleAsync(context, exception) — the exact seam the [L03.01.01.19] Pipeline exception boundary, status-code pages, and 404 terminal over IResult (supersedes #776) #881 exception boundary invokes.

Design decisions recorded in docs/DESIGN.md (per the acceptance criteria)

• Faults vs outcomes — the line both packages hold: expected protocol outcomes (401 challenge, 404, 415) stay each feature's normal imperative response path and are never thrown; the hook is for faults only (key ring unavailable, missing serialization contract). The registry's feature surface is non-throwing (GetReader/GetWriter → null) so outcome-producing layers branch to 415/406 without exceptions; only the call-site conveniences throw (HttpContentSerializationException, a fault for the hook).
• Package homing under the hosting-isolation rule — the issue's open question, decided by the default handler: it renders Web.ProblemDetails, the area root must not reference feature packages, so the hook lives in a feature package (Web.ErrorHandling → Http, Web, Web.ProblemDetails), not an area-root seam. Web.Hosting references neither package (COHRES001/002 clean); delivery is via the App.Web shared framework; the server's [L03.01.01.01.04] Rewrite WebApplicationServer: per-connection dispatch, error isolation, disposal, graceful stop #762 last-resort isolation stays infrastructure-level and never invokes the hook (three-layer model recorded in DESIGN.md).
• Non-generic contracts, generic extensions — registry interfaces take (object? value, Type type) (no generic virtual dispatch under AOT; heterogeneous storage); ReadContentAsync<T>/WriteContentAsync<T> forward typeof(T).
• Matching is [L01.01.11.38] Add HttpMediaType value object and Accept/quality-value negotiation primitives #771 semantics, nothing invented — HttpMediaType.Includes + Specificity ranking + registration-order tie-break, so [L03.01.02.01.02] Implement result writers and content negotiation primitives needed by common endpoint scenarios #149's negotiation and the registry can never disagree. application/*+json suffix ranges are deliberately not a match rule (recorded; HttpMediaType.Suffix is there for [L03.01.02.01.02] Implement result writers and content negotiation primitives needed by common endpoint scenarios #149).
• AddErrorHandling().OnError(...) chain, not builder.OnError(...) — a root-level repeatable-looking verb would silently replace the name-keyed feature and drop earlier handlers; the auth-idiom chained builder makes repetition safe. Composition/ordering question answered structurally: registration order = consultation order, first-true wins, terminal default is not a registration (overriding = registering a handler that always handles).
• ReadContentAsync/WriteContentAsync naming — the issue's response.WriteAsync(value) sketch was kept ergonomically but renamed: an unconstrained WriteAsync<T> would silently change overload binding for string the day a raw-text WriteAsync helper appears.

Deliberately not in this PR (the fan-out this seam exists for)

• [L03.01.01.19] Pipeline exception boundary, status-code pages, and 404 terminal over IResult (supersedes #776) #881 — exception-boundary middleware, status-code pages, 404 terminal (consumes IHttpErrorHandlingFeature; pipeline tests here demonstrate the boundary shape inline).
• [L03.01.02.01.02] Implement result writers and content negotiation primitives needed by common endpoint scenarios #149 — Accept-driven negotiation over the registry (selects the media type, passes it through the explicit WriteContentAsync overload).
• [L03.01.02.03] Source-generated endpoint parameter binding and validation framework (AOT) #796 — source-generated binding + validation (validation sits between deserialization and the handler; recorded as adjacent-not-here in DESIGN.md).

Wiring (new-Web-project checklist)

• frameworks/Assimalign.Cohesion.App.props — both assemblies added to the App.Web ItemGroup (no new outside-area transitive deps needed); validated via dotnet pack of App.Web.Runtime.
• .github/workflows/resource-web.yml — both projects added to the CI matrix (COHRES guard executes per project).
• resources/Web/Assimalign.Cohesion.Web.slnx + root Assimalign.Cohesion.slnx — src/tests/docs entries.
• resources/Web/README.md — project-map rows.
• docs/OVERVIEW.md + docs/DESIGN.md per package.
• Note (Batch-4a collision): sibling Wave-4a sessions touch the same App.props/CI-matrix lines — trivial rebase expected, as planned.

Tests

39 new tests (27 serialization, 12 error handling), all green: registry matching semantics (specificity, ties, parameterized types, null on no match), JSON round-trips over the source-generated TestJsonContext (web-default camelCase, contract faults, format-native JsonException propagation), chain semantics (order, first-wins, handler-fault propagation, default rendering, no-internals-leak), plus full-pipeline tests over the merged #793 WebApplicationTestFactory: typed body round-trip end-to-end, middleware branching to a 415 outcome via the non-throwing surface, an escaped fault rendering as problem+json 500 through an inline boundary, and a registered OnError handler owning a 503 response.

Acceptance-criteria note

The issue gated implementation on an owner design review; the owner's session brief for this item directed full implementation → PR. The docs/DESIGN.md files are the recorded design (registry shape + AOT story, hook contract + default behavior, faults-vs-outcomes, homing), and this PR review is that owner gate — if any recorded decision should go the other way, the seams are small enough to pivot before merge.

Closes #864

🤖 Generated with Claude Code