Recognise all recoverable schema incompatibilities in vstream plan failures

[orware]

Problem

IsVStreamSchemaIncompatibilityError (added in #89) requires Code: FAILED_PRECONDITION in the error text.

vstreamer wraps every plan failure with failed to build table replication plan for table <name>, but the inner cause varies with the shape of the DDL — and only two are raised through vterrors with a code attached. The rest are plain fmt.Errorf, so they arrive code-less and the matcher rejects them on its very first check:

Inner cause	Raised when	Has a code?	Matched before?
column <c> not found in table <t>	column appended, stream now requests it, event predates the ALTER	yes	yes
cannot use column names in vstream filter ...	columns inserted mid-table (ADD COLUMN ... AFTER) or reordered	yes	yes
cannot determine table columns for <t>	column dropped, schema narrower than the event	no	no
failed to build ENUM and SET column integer to string mappings	ENUM/SET column dropped, value list unrecoverable	no	no

Two of the four were unmatched, and both have been seen in production. Each falls through to the generic error return, so the operator gets an opaque Internal error rather than the FailedPrecondition and the explicit "run a historical re-sync" guidance #89 added — precisely the situations that guidance exists for.

All four recover the same way: drop the cursor, run a historical sync.

Change

Gate on the failed to build table replication plan wrapper — common to all variants — and enumerate the four recoverable inner causes. The FAILED_PRECONDITION check is removed rather than relaxed: it excluded real failure shapes while adding no selectivity the wrapper does not already provide.

What is deliberately excluded

The wrapper is not sufficient on its own. Two other errors share it and are not recoverable by re-syncing. Both have negative tests:

• unsupported type: <n>, position: <i> — a historical sync would hit the same unsupported column type.

• unknown table <t> in schema — this one is worth spelling out, because it looks like a stale-cursor condition and isn't. historian.GetTableForPos returns (nil, nil) on a miss, and Engine.GetTableForPos then falls back to the live schema rather than erroring:

  if mt != nil { return mt, nil }
  // We got nothing from the historian, which typically means that it's not enabled.
  // ... falls back to the live schema

  So the historian fails open, and this error instead means an undecodable GTID or a table genuinely absent from the tablet's schema. The latter can be transient during an online DDL rename swap, where resetting the cursor would force an unnecessary historical sync.

Tests

Eight table-driven cases — four positive, four negative. The two newly matched positives were each verified to fail against the previous matcher.

go test ./lib passes. (./cmd/... needs make proto first, as CI does via test-ci: proto.)

Relationship to #97

Independent, and they compose. #97 adds opt-in automatic recovery once a schema incompatibility is detected; this PR determines what counts as one. Either can merge first — but detection without #97 only improves the error message, and #97 without this one only auto-recovers from two of the four causes.

🤖 Generated with Claude Code

[orware]

Reproduced all four matched causes end-to-end against live PlanetScale branches, driving the connector's real Read() path — capture a cursor, write rows, apply the DDL, write more rows, resume from the stale cursor. Both via direct ALTER and via deploy request (online DDL), with and without track-schema-versions. 16 cells; every deploy-request result was identical to its direct-ALTER equivalent.

Three of the four matched causes reproduce exactly and are caught by this matcher:

DDL	error	matched
trailing ADD COLUMN	column X not found in table Y	yes
mid-table ADD ... AFTER	cannot use column names in vstream filter	yes
DROP COLUMN	cannot determine table columns	yes

One caveat worth recording so it isn't mistaken for verified: I could not reproduce the ENUM variant (failed to build ENUM and SET column integer to string mappings). Dropping an ENUM column hits the column-count check first and surfaces as cannot determine table columns; with schema tracking enabled it decodes cleanly. The production sighting that motivated that clause was on a mysql80-2026-04-08 build, so the upstream issue looks to have been fixed since.

I've left the clause in — it matches a real error that was observed in production, and it's inert if the error no longer occurs — but happy to drop it if you'd rather the matcher only cover shapes reproducible on current builds.