Skip the body copy on a StreamOne 304, and close the revision-ETag test gaps

[jeremydmiller]

Follow-up to #5121 (merged as 0e8daed), addressing the review points raised there. No behavior change to the ETag values themselves — same headers, same 304 semantics — plus one documentation correction where the shipped docs describe behavior the code does not have.

Efficiency

A 304 no longer buffers the document body. VersionSelectClause appends mt_version after data, but every reader accesses columns by GetOrdinal(name) and Marten never opens readers with CommandBehavior.SequentialAccess — so the row is fully buffered and read order is free. StreamOneWithVersion now reads the version first and consults a shouldWriteBody predicate before copying the payload. On a conditional-request hit WriteSingle declines the body, so the pooled MemoryStream is never grown and the document is never copied. The row still comes back from Postgres either way; this saves the copy, not the read. Benefits the Guid path identically.

No more boxing on the revision read. Convert.ToInt64(GetFieldValueAsync<object>(...)) is replaced with a GetFieldType branch picking GetFieldValueAsync<int> or <long> directly — same #4614 both-widths robustness, one less allocation per request on the projection read path.

The two duplicated reader methods collapse into one. StreamOneWithVersion and StreamOneWithRevision were near-verbatim copies differing only in the CLR type read back; they are now a single method taking a numericRevision flag, and MartenLinqQueryProvider has one branch instead of two. StreamOneJsonResult/StreamOneReadResult gain BodyWritten.

Test coverage

Six new tests, all Alba end-to-end through theHost.Scenario against real minimal-API endpoints except where noted:

• stream_one_with_revision_etag_executes_a_single_db_command — the companion to the existing Guid-path acceptance test. The revision flavor is the projection read-model path, so pin that document + ETag resolve in ONE round trip. (Direct WriteSingle against a counting IMartenSessionLogger, matching the existing test's shape.)
• stream_one_does_not_buffer_the_document_body_on_a_304 — pins the change above: a 20KB projected document with a matching If-None-Match leaves the response buffer at zero length.
• stream_one_emits_revision_etag_for_long_versioned_document — new LongVersionedIssueNote : ILongVersioned keeps the bigint column where IRevisioned narrows to integer (UseTenantPartitionedEvents is incompatible with optimistic appends / FetchForWriting (aggregate handlers) #4614), so the pair now covers both widths on purpose rather than incidentally.
• stream_one_returns_404_without_etag_for_a_revisioned_document — the 404-leaks-no-header pin existed only for the Guid path.
• stream_one_suppresses_etag_on_a_revisioned_document_when_emit_etag_is_false — likewise for the EmitETag = false opt-out, and asserts the document is still served rather than only the header dropped.
• interface_driven_revisions_plus_optimistic_concurrency_fails_fast (EventSourcingTests) — the likeliest real-world route into Derive the StreamOne ETag from the numeric revision for revisioned documents #5121's new guard and the one neither existing guard test covers: nothing in the configuration says "numeric revisions", VersionedPolicy turns them on because the type implements IRevisioned, and a fluent UseOptimisticConcurrency(true) layers the Guid version on top. Verified against master before the guard: this reached the database as MartenSchemaException: DDL Execution ... Failed from two mt_version columns.

Documentation correction

docs/documents/aspnetcore.md claimed EventProjection output documents "emit no ETag unless they opt into a versioning flavor themselves". They do emit one. ProjectionDocumentPolicy only forces numeric revisions onto aggregate projection targets, so an EventProjection's output keeps the plain-document default — Guid version metadata — and emits a quoted GUID ETag that changes on every projection write. That is a usable cache validator but is not a stream version and does not line up with StreamAggregate<T>. stream_one_emits_a_guid_etag_for_an_event_projection_output_document pins the real behavior against a new OrderTouchProjection in IssueService.

Also: #5121's fail-fast guard shipped undocumented. docs/documents/concurrency.md now carries a warning naming both routes into the invalid state, since neither reads as "I asked for both flavors".

Deliberately not included

• The UseOptimisticConcurrency / UseNumericRevisions asymmetry. MartenRegistry.UseNumericRevisions clears Metadata.Version.Enabled, but UseOptimisticConcurrency does not clear Metadata.Revision.Enabled — so one order is last-wins and the reverse is now a hard bootstrap throw. Making it symmetric (and narrowing the guard to projection targets via Projections.TryFindAggregate) is a behavior change to document configuration that deserves its own PR and its own discussion.
• WriteSingle with a Select() projection throws IndexOutOfRangeException : Field not found in row: data. Reproduces identically on master at de63fc5, so it is a pre-existing StreamOne<T> ETag: inline mt_version (eliminate 2nd round trip) + reverse where T:notnull + ETag test hardening (pre-9.18, follow-up to #5015) #5027/StreamOne<T> ETag: inline mt_version (one round trip) + drop notnull + ETag test hardening (#5027) #5030 regression, not a Derive the StreamOne ETag from the numeric revision for revisioned documents #5121 one: FindMapping(typeof(T)) for the projected/anonymous T returns a fresh mapping whose Metadata.Version.Enabled defaults to true, so VersionSelectClause gets appended to a select that has no data column. Filed as StreamOne/WriteSingle with a Select() projection throws "Field not found in row: data" when emitETag is on (regression in 9.18.0) #5158.

Verified locally (net10.0)

Marten.AspNetCore.Testing 107/107 · EventSourcingTests guard file 3/3 · LinqTests, DocumentDbTests, EventSourcingTests full suites clean. markdownlint and cspell clean on the changed docs.

🤖 Generated with Claude Code