feat(core): .AsStream() catalog view + deferred streaming Load()

[Spelkington]

Parent

#112

What to build

The catalog surface for streaming reads: a .AsStream() container-axis modifier and the deferred streaming Load() path. .AsStream() derives a read-only streaming view of an existing eager item — IItem<IEnumerable<T>> → IReadOnlyItem<FlowSource<T>> — read-only because composed streaming writes are out of scope. It is gated to composed formats that can actually stream (via the streaming-decode marker); calling it on a direct storage adapter (EFCore/Sheets/GQL, which have no format serializer) is a design-time/pre-flight error, never a silent materialize.

Requires a capability seam on the composed storage adapter (exposing the medium + reader) that also composes through the constrained-adapter wrapper. Streaming Load() is a new deferred-acquisition path — it returns a FlowSource description that brackets the medium open on first pull; it is not an eager container adapter (whose FromRows returns an eager Task<T>). Typed schema-mismatch translation is performed in the storage-layer per-pull producer (the Prelude cannot see SchemaMismatchException), preserving the typed RuntimeError.SchemaMismatch the eager path gives.

Design: ADR-0023.

Acceptance criteria

• .AsStream() derives IReadOnlyItem<FlowSource<T>> from an eager item via a capability seam that composes through the constrained-adapter wrapper.
• Streaming Load() opens the medium on first pull (deferred), not eagerly; fan-out (two consumers) re-acquires, matching eager multi-consumer behavior (test).
• .AsStream() on a direct adapter (no IFormatStreamReader) fails at design-time/pre-flight — never wraps an eager load in a FlowSource.
• A mid-stream schema mismatch surfaces as typed RuntimeError.SchemaMismatch (not External), matching the eager path (test).

Blocked by

• feat(core): FlowSource<T> — minimal streaming effect primitive (compile-to-FlowIO) #113

[Spelkington]

Implemented in 0c93be33758bb9cd581dcb832416f885e22b350c on branch feat/flowsource-primitive.

.AsStream() derives IReadOnlyItem<FlowSource<TRow>> from an eager collection item. The seam is ISupportsStreamingView<TRow> on ComposedStorageAdapter: OpenStreamingSource() brackets medium.ReadStream() (acquired on first pull, released on every exit path) over reader.DeserializeRows, and reuses TranslateSchemaMismatch so a mid-stream SchemaMismatchException lands as the typed RuntimeError.SchemaMismatch — translation stays in the storage layer, never the Prelude. Streaming Load() is a distinct deferred path (returns a FlowSource description), not an eager IContainerAdapter. Gated to IFormatStreamReader formats (direct adapters / non-streaming formats throw at wire-up); a .Constrain() wrapper is unwrapped to reach the composed format; the view is read-only.

8 AsStream tests + 291 core tests green. Leaving open — to be closed on merge to main.