Observability: frontend error reporting — ErrorBoundary → API + traceparent + sourcemaps (#217)

[mforce]

Closes #217 — the last slice of the observability program (#214 traces, #215 metrics, #216 handler logs).

What

API — POST /api/v1/client-errors (anonymous, no storage)

• One structured Error-level log line per report: Client error ({Scope}) at {Route}: {Message} with Stack, ComponentStack, AppVersion, ClientTraceId attached as structured properties via the provider scope (Observability: structured logs at domain state transitions #216 mechanism).
• Hostile-caller posture by design (the endpoint is anonymous — the login screen can crash too):
  • Per-IP rate limit: new client-errors fixed-window policy (default 10/300 s) on the Security: rate limiting on anonymous auth endpoints (login/refresh) #143 rate-limiting infrastructure; documented in deploy/.env.example.
  • 16 KB byte cap: declared oversize refused without reading a byte; body read by a capped manual loop (the Farm settings — profile (name/logo) + locale/timezone/currency editing + §4.6 currency-change guard (API + SPA) #123 logo-upload pattern), so a lying or absent Content-Length changes nothing.
  • Per-field truncation (message 2 000 / stacks 8 000 / route 500 chars) so one report can't balloon a log line even under the cap.
• Responds 202; malformed JSON, blank message, or unknown scope → 400; oversize → 413.
• The shared 429 problem detail is now request-neutral wording (it used to say "authentication attempts"; the policy now also guards a non-auth endpoint).

SPA

• web/src/lib/traceparent.ts — every API request (JSON + blob paths) now carries a W3C traceparent minted client-side (crypto-random, all-zero ids guarded), so a browser action correlates with the API request log and spans from Observability: activate the telemetry pipeline — OTLP trace export, request logging, TraceId↔log correlation #214. The client remembers the last trace id — a failed request's id is exactly the one worth having.
• web/src/api/errorReport.ts — best-effort by contract: plain fetch (no bearer, no refresh churn, no idempotency key), keepalive: true so the report survives the fallback's Reload, client-side truncation mirroring the server, and the returned promise always resolves.
• ErrorBoundary.componentDidCatch posts the report (message, stacks, scope, location.pathname) fire-and-forget; the fallback UI cannot be broken or delayed by it.
• Production build emits hidden sourcemaps (.map files, no sourceMappingURL comment) so reported minified stacks resolve to source lines; verified 115 sources with embedded content in the build output.

Tests — TDD, RED verified before implementation:

• 8 API integration tests (ClientErrorReportTests, dedicated factory: sink tap + fake remote IP + tight limit): structured-fields log, app scope, 413 + not-logged, blank message 400, unknown scope 400, per-IP 429 + independent buckets, truncation.
• 16 SPA tests: traceparent shape/uniqueness/zero-guard, header on JSON + blob requests, last-trace-id capture incl. failed requests, report payload/truncation/trace-id join, network-failure + 429 swallowing, boundary report + scope + fallback-survives-report-failure.
• FakeRemoteIpStartupFilter promoted from RateLimitingTests to shared infrastructure (auth rate-limit tests unchanged, still green).

Acceptance criteria

• Render error in either scope → one structured Error log line with message, stacks, scope, route
• Endpoint rejects oversized payloads (413) and is rate-limited per IP (429 + Retry-After)
• Reporting failure never breaks or delays the fallback UI (contract + test)
• Vitest tests for the reporting path (standing web/ rule)
• SPA requests carry traceparent; the id becomes the request log's TraceId (Observability: activate the telemetry pipeline — OTLP trace export, request logging, TraceId↔log correlation #214's Incoming_traceparent_becomes_the_logged_traceid covers the server half)
• Production build emits sourcemaps; stacks resolve (hidden variant, sources embedded)
• Build clean; SPA coverage gate green (lib/** 100 % lock holds for the new traceparent module)

Verification

• .NET: 765 tests green ×2 (parallel-flake check)
• SPA: 633 tests green; coverage thresholds pass
• dotnet build: 0 warnings, 0 errors

No GLOSSARY/Help update: nothing user-visible changed (the fallback UI is untouched; reporting is invisible to the user).

[mforce]

Review round outcome (codex + pi + 2 Claude agents)

19 findings across 4 reviewers → 6 accepted (fixed in c89fc2e), 13 rejected with evidence. Several findings were duplicates across reviewers; grouped below.

Accepted → fixed

#	Finding (reviewers)	Fix
1	CR/LF/ANSI in anonymous message/route can forge extra plain-text log lines under {Message:lj} (codex #2, pi #1's valid half)	Control characters stripped from the two console-rendered args; stacks stay verbatim in structured properties the console template never renders. Regression test asserts \n/\r/ESC gone from Message/Route, preserved in Stack.
2	Client per-field caps sum to ~18.5 KB > server 16 KB cap → deepest legitimate reports silently 413'd (codex #3, Claude-agent Important)	Budget is now the serialized body in bytes: 15 KB, all sized fields shrink by halves until it fits. Tests pin worst-case ASCII and all-multibyte (💥) payloads ≤ 15 000 bytes.
3	.map files publicly served from wwwroot at predictable URLs → full original sources disclosed; workbox maps also carried sourceMappingURL comments (codex #4, Claude-agent Critical)	Dockerfile parks every .map under /app/sourcemaps (operator: docker cp to resolve stacks — AC still met); workbox no longer emits maps at all. Verified: 0 sourceMappingURL comments, only the app map in dist, moved out of the served tree.
4	Crash-report POST carries no traceparent, inconsistent with "every SPA request" (codex #6)	Report POST mints its own traceparent; payload traceId still points at the crashed screen's last request (the causal one). Test added.
5	Oversize coverage only exercised the declared-Content-Length early exit (codex #7 + pi #4)	New integration tests: chunked body with no Content-Length (the capped-read-loop path), body exactly at the cap (202), one byte over (413), missing message, non-JSON body.
6	Whitespace-only message passes the client, server 400s it, report lost (cavecrew #4)	Client trims before the emptiness check → "(no message)" placeholder. Test added.

Rejected — with evidence

• Template/log injection via {braces} in message (cavecrew Scaffold .NET solution #1, pi Scaffold .NET solution #1's mechanism): values are bound Serilog arguments; the template is a compile-time constant. Braces in argument values are rendered literally, never parsed. (The CR/LF rendering concern was the valid half — fixed above.) The Claude agent independently confirmed: "correctly avoid log-injection via structured template parameters."
• PR "removed" BeginScope/preserveStaticLogger (cavecrew Fix egg-farm spec gaps: hen-day math, egg unit conversion, regrade path #2, Bump to v4.4: README, CHANGELOG, and spec version line #3): hallucinated — git diff --stat origin/main..HEAD shows TenantResolutionMiddleware.cs untouched and the Program.cs delta is rate-limiter registration + group mapping + one using.
• apiGetBlob missing from test imports → compile error (pi Fix egg-farm spec gaps: hen-day math, egg unit conversion, regrade path #2): it's in the existing import list; tsc -b (pre-commit) and the full Vitest suite pass.
• Surrogate-pair truncation corrupts JSON (pi Bump to v4.4: README, CHANGELOG, and spec version line #3): .NET and JS JSON serializers escape a lone surrogate as U+FFFD — output stays well-formed; a truncation tail is lossy by definition.
• 429'd requests still log Information completions → flood (codex Scaffold .NET solution #1): true of every public endpoint including login/refresh since Security: rate limiting on anonymous auth endpoints (login/refresh) #143 — one bounded completion line per HTTP request is the request log working as designed, and suppressing 429s would hide the attack signal operators want.
• lastTraceId start-time race (codex [A1] Seed default farm/house/user + startup migrate + flock CRUD #5): documented heuristic; completion-time capture has the converse race and failed requests never complete. Correlation hint, not causal proof.
• Move validation/logging into a handler + FluentValidation (codex [C1] Generate egg lots from daily entry (missing bridge) #8): the endpoint has zero domain semantics — pure telemetry transport with a bounded read, same inline pattern as AuthEndpoints/FarmLogoEndpoints. A handler would add ceremony, not safety.
• Theoretical infinite loop in all-zero guard (cavecrew [A1] Seed default farm/house/user + startup migrate + flock CRUD #5): each iteration is independent with P(all-zero) = 2⁻¹²⁸; a retry counter is dead code by construction.

Verification after fixes

• .NET: 770 green ×2 (417 integration incl. 18 client-error tests)
• Web: 637 green, coverage gate + lib/** 100 % lock hold
• Build: 0 warnings / 0 errors; SPA build verified (app map emitted, nothing map-shaped served)