experimental_csv: breaking output contract changes (tracked)

[apstndb]

Context

Follow-up from spanvalue v0.5.0 adoption (#38) and CSV RowIterator refactor (#39). Items here change observable output or defaults; ship behind explicit flags or a documented major bump, not as drive-by behavior changes.

Related upstream: spanvalue v0.5.0 (Simple NUMERIC wire-as-is, writer constructor errors).

Scope (one or more PRs)

1. Optional CSV formatter preset (flag required before any default flip)

Today --format=experimental_csv uses spanvalue SimpleFormatConfig via NewCSVWriter (wire-faithful scalars; NUMERIC as returned on the wire).

Proposed: add something like --csv-format=simple|spanner-cli mapping to:

• spanvalue.SimpleFormatConfig() (current default)
• spanvalue.SpannerCLICompatibleFormatConfig() (CLI-like NUMERIC trim, STRUCT/bracket rules, etc.)

Breaking only if we later change the default from simple to spanner-cli without a major version bump. Implement the flag first; document default stability.

2. Default / major-version policy

• Document that experimental_csv output may change when spanvalue minor versions bump; golden tests in testdata/experimental_csv/ are the contract.
• If we ever align CSV defaults with spanner-cli, treat it as a breaking release note item.

3. jq / yaml output (larger, optional split)

json/yaml paths use jqresult + protojson, not spanvalue formatters. Adopting spanvalue JSONFormatConfig / LiteralFormatConfig for cell rendering would change scalar and STRUCT appearance vs today and is a separate breaking track—only pursue with an explicit format version or new --format choice.

Out of scope for this issue

• Non-breaking additions (stats side channel, headerless CSV, new formats) → see the companion issue below.
• WriteRowIterator migration → #39.

Acceptance

• CSV formatter preset is opt-in via flag; default remains Simple until a deliberate breaking release.
• README / release notes describe output contract and when users should pick spanner-cli.

[apstndb]

Companion (non-breaking): #41