[matt-welch]

Description

When a Vamana index fails to load, the worker-mediated search path showed clients only a generic "index not loaded" error with SQLSTATE XX000, even though the worker had already logged the real cause to the server log. INSERT and VACUUM, which check the index directly on the backend, always surfaced the real error with a hint; only SELECT lost it on the way through the worker.

VamanaWorkerGetOrLoadIndex in src/vamanaworkerindex.c now records the sqlerrcode, message, and hint of a load failure right before it is logged and freed, in worker-local state (the worker is single-threaded, so only one load is ever outstanding). A new VamanaWorkerGetLastLoadError() accessor exposes it. The generic "not loaded" error in src/vamanaworkersearch.c, raised when a load attempt returns nothing usable, now forwards that real error (as SQLSTATE 22000, data exception) instead of a message with no connection to the actual cause.

test/t/01_persistence.pl had an existing test for a non-finite vector value forcing a failed index rebuild; it asserted the old generic client-facing message, which this change replaces with the real one, so that assertion was updated.

Added test/t/68_vamana_metapage_format_upgrade.pl: it patches a real index's on-disk magic number back to the value used before the on-disk format changed, then drives it through INSERT, VACUUM, SELECT, REINDEX, REINDEX CONCURRENTLY, and DROP INDEX, confirming each either fails closed with the correct error and hint or restores service, and that the worker never crashes.

docs/USER_GUIDE.md gained an "Upgrading the Extension" section explaining that an on-disk format change requires rebuilding affected indexes with REINDEX, since there is no ALTER EXTENSION ... UPDATE path that can rewrite index pages, plus a REINDEX trigger bullet, a troubleshooting entry for the error text, and a cross-link from the existing halfvec upgrade note.

Related Issues

Type of Change

• Bug fix
• New feature
• Refactor / code cleanup
• Documentation update
• Test addition or update
• Build / CI change

Pre-Merge Checklist

Build

• make completes without errors or warnings
• make install completes successfully

Tests

• If this PR introduces no new behavior: existing regression tests (make installcheck) and TAP tests (test/t/) pass with no failures
• If this PR introduces new behavior: test cases covering it were added to test/sql/ and/or test/t/
• If this PR adds a standalone unit-test module under test/modules/: it builds and passes (make -C test/modules/<module> installcheck)

Documentation

• Relevant docs under docs/ updated if architecture or usage changed

Testing Notes

Full TAP suite run via the project's build-and-test tooling: 61 files, 1386 tests, all passing, including the new test/t/68_vamana_metapage_format_upgrade.pl (25 assertions) and the updated test/t/01_persistence.pl. SQL regression suite run separately: 8 files, all passing.

The error-forwarding change was verified by reverting it (git apply -R on just that part of the diff), confirming the three assertions tied to it fail for the expected reason, then reapplying and confirming they pass again.

The new TAP test's own corruption mechanism was verified the same way: with the magic-number patch made a no-op, the INSERT and VACUUM failure assertions correctly report failure, confirming the test actually exercises the failure path rather than passing regardless.

[asonje]

src/vamanaworkersearch.c:172 hardcodes slot->errorCategory = VAMANA_ERR_DATA; regardless of what the load actually failed with, even though loadErrSqlerrcode (VamanaWorkerGetLastLoadError's first out-param) is captured right above it and never used otherwise.

This project already has the right codec for this: VamanaCategorizeSQLState(int sqlerrcode) (src/vamanaworkershmem.c:1366-1376), used the same way at three existing call sites in vamanaworkerwrite.c (579, 772, 848). Swapping in slot->errorCategory = VamanaCategorizeSQLState(loadErrSqlerrcode); would make the client-visible SQLSTATE for a worker-mediated SELECT match the real failure (e.g. ERRCODE_OUT_OF_MEMORY/ERRCODE_IO_ERROR) instead of always reporting
ERRCODE_DATA_EXCEPTION, consistent with how the message/hint are already forwarded verbatim.