fix(vector): Azure document keys cannot start with an underscore - #235
Merged
Conversation
Every Knowledge Engine upsert and delete against Azure AI Search was failing in production with Invalid document key: '_b64_YWtiYW5r…'. Keys cannot start with a leading underscore. The marker for base64-encoded ids was `_b64_`. Azure's key rule is the charset (letters, digits, underscore, dash, equals) AND "may not start with an underscore"; the code carried the first half and not the second, so the marker itself was illegal and no id needing encoding could ever be written. The marker now starts with a letter (`b64_`), and SAFE_KEY_PATTERN rejects a leading underscore so a caller id like `_foo` is encoded rather than passed through to the same rejection. Decoding still accepts the old marker; nothing was ever written under it, since every such write failed. The contract suite did assert the produced key against a pattern — the pattern was the same incomplete rule, so it accepted `_b64_` and stayed green while production rejected every batch. The pattern now carries the whole rule, and a sweep asserts it for the id shapes a real deployment sends. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Production is failing right now. Every Knowledge Engine upsert and delete against Azure AI Search is rejected:
Cause
Azure's document-key rule has two halves: the charset (letters, digits,
_,-,=) and "may not start with an underscore". The code carried the first half only, and the marker chosen for base64-encoded ids was_b64_— so the marker itself was illegal and no id that needed encoding could ever be written. Knowledge Engine ids aremodule:documentId:chunkIndex, so every one of them needs encoding.Fix
b64_.SAFE_KEY_PATTERNrejects a leading underscore, so a caller id like_foois encoded rather than passed through to the same rejection.Why the tests did not catch it
The contract suite did assert the produced key against a pattern. The pattern was the same incomplete rule, so it accepted
_b64_and stayed green while production rejected every batch. A mocked SDK can only check what the assertion knows, so the assertion now carries the whole rule, and a sweep asserts it across the id shapes a real deployment sends — including the one from the production error.tscclean · 3734 tests ·npm run buildclean.🤖 Generated with Claude Code
https://claude.ai/code/session_01KG71cnyfK5GGwbXb25pxsd