sinks: a value the driver cannot encode fails once, as a user error

[turbolytics]

What this changes

A value the sink's driver could not encode was retried the full backoff ladder and then reported as system.sink.unreachable (#233). Nothing was unreachable. The destination was up, the fault was one value, and the exit code told a supervisor to restart into the same failure.

Two layers caused it:

• The ClickHouse sink returned the driver's Append error with no code.
• retryable listed three codes it would not retry and retried everything else. user.sink.type_unsupported was not on the list. Walking the registry shows user.config.not_found took the ladder too.

The fix:

• A new code, user.sink.encode_failed, names a value the sink's client refuses before anything reaches the network. It is class user and exits 10.
• retryable decides by class. Any user code and system.sink.write_failed make one attempt. system.sink.unreachable and uncoded errors are retried as before, because a driver timeout arrives without a code.
• The ClickHouse sink wraps the Append error with the new code. PrepareBatch and Send keep sinkError, because that is where bytes cross the network.
• The README gains a "Sink retries" subsection. It documents the retry block and states the rule as a table keyed by error code. The retryable doc comment carries the same table and names the section.

What breaks if this is wrong: a transient fault that some sink coded as user stops being retried. No sink does that today. TestSinkRetry_NoUserCodeIsRetried walks the registry, so a user code added later cannot fall back into the ladder. TestSinkRetry_UncodedErrorRunsTheWholeLadder pins the other direction.

Closes #233.

Verification

• go test -short -race ./... passes with no data races. The only output is pre-existing macOS LC_DYSYMTAB linker warnings.
• uv run --locked pytest tests/tooling -q: 205 passed.
• make coverage-page && git status --short docs/coverage is clean, after committing the regenerated matrix.md, which renders the edited invariant claim.
• uv run --locked pytest tests/release -q was not run. No CLI surface, flag, Dockerfile, or build-stamped value changed.
• make soak was not run, because it cannot observe this change. scripts/soak.sh runs dev/config/soak/inferred.noop.yml by design, and the noop sink is not wrapped in the retry ladder. No line in this diff executes under the soak. Both changed paths run only when a flush fails, so the happy path allocates as before.

The live ClickHouse tests ran rather than skipped. TestSinkClickhouse_InsertsRows, InsertsArrays and StringTemporalsAreNotShiftedByHostZone passed against a local server.

Acceptance: the issue's own repro

The config from #233, run against a local ClickHouse DateTime column, with one message {"label":"isoz","ts":"2026-09-01T12:00:00Z"}:

$ ./bin/sqlflow run iso-probe.yml --max-msgs 1
Error: [user.sink.encode_failed] clickhouse sink: encode row: clickhouse [AppendRow]: dt_plain parsing time "2026-09-01T12:00:00Z" as "2006-01-02 15:04:05": cannot parse "T12:00:00Z" as " "
$ echo $?
10

The run logged no retry lines, and the log records error.class as user. The issue reported the same repro on v1.0.6 as four attempts and system.sink.unreachable, which maps to exit 12.

Notes for the reviewer

• user.sink.encode_failed is separate from user.sink.type_unsupported. Type unsupported is a column whose Arrow type the sink cannot convert. That is a schema property and fails every row. Encode failed is one value in a supported column. An operator reading "type unsupported" for a badly formatted string would look at the wrong thing.
• Iceberg is unchanged and still retries an encode failure. iceberg-go converts and writes in one AppendTable call, and its conversion errors cannot be told from I/O errors without string matching. A false "permanent" on a transient Iceberg fault would drop a batch, which is worse than wasted attempts.
• The issue's ISO 8601 timestamp still fails. It now fails fast and clearly. Accepting RFC 3339 in temporalFromString is a type-matrix change with an open Python-parity question, left as a follow-up.
• The sink.error.classifies coverage row stays missing for every sink. The invariant is verified_by: harness, and unit tests do not fill a harness cell. That was already true before this branch.
• The spec and plan are under docs/superpowers/.