Make SDK ingestion docs agent-friendly

[elenagaljak-db]

What

Reworks the ingestion documentation across all five SDKs (Rust, Python, TypeScript, Java, Go) plus the root docs so that clients — including AI coding assistants — write performant code by default.

Why

Users (and agents) were producing slow clients that call the wait-for-acknowledgment method (wait_for_offset / waitForOffset / WaitForOffset, or .join() on a per-record future) after every ingest. Because ingestion is asynchronous and pipelined, waiting per record forces a full server round-trip before the next record is sent, limiting throughput to ~one record per round-trip. The docs were partly to blame: every SDK led with the per-record-wait example, and the high-throughput pattern was buried far below.

Changes

• Lead with the idiomatic flow — ingest in a loop, then flush() once — as the first example in every README. Per-record waiting is presented as a legitimate tool for low-volume "confirm this specific record" cases, not the default.
• Positive framing: a new "Acknowledgments and throughput" section explains how acks work, positioned after the API descriptions (JSON / Protobuf / Arrow) rather than wedged before them.
• API doc comments updated where consumers actually see them: Rust ///, Python docstrings (sync + async), TypeScript JSDoc, Java Javadoc, Go godoc — on ingest_*, wait_for_offset/flush and equivalents.
• Examples: single-record examples now ingest-then-flush() once.
• Java QuickStart rewritten off the deprecated ingestRecord().join()-in-a-loop onto ingestRecordOffset() + wait-once.
• CLAUDE.md (root + per-SDK) gain a "client code patterns" / performance rule for in-repo agents.
• NEXT_CHANGELOG.md updated in each SDK under Documentation.

Notes

• The "wait on the last offset confirms all prior" guidance is verified against the Rust core: the ack watermark is monotonic (wait_for_offset_internal waits for last_received_offset >= target).
• Ack callbacks exist only in Rust/Python/Java; the TS and Go docs use the flush()/last-offset approach (no invented APIs).
• Verified: Rust doctests pass, Rust examples compile, Go is gofmt-clean, Python compiles. Docs/prose only — no library logic changed.

This pull request and its description were written by Isaac.