retrofit: reverse-spec vector-embeddings capability (5 REQs)

[rubenvdlinde]

Summary

Reverse-spec retrofit that mints a new vector-embeddings capability and annotates the existing implementation against it. No behaviour change — annotation + spec only.

The new capability documents 5 REQs, one per domain:

1. Multi-provider embedding generation (OpenAI / Fireworks AI / Ollama) with a cached generator factory, model-to-dimensions fallback, and the admin "test embedding" validation path.
2. Backend-routed vector storage (Postgres openregister_vectors PHP-serialised BLOB or Solr atomic update) with UTF-8 sanitisation and entity-type-aware document IDs.
3. Strategy-driven batch vectorisation orchestrator (VectorizationStrategyInterface, serial/parallel modes, per-entity error capture).
4. Object vectorisation strategy (JSON-serialise, multi-field title/description fallback, register/schema/uuid/uri metadata folding).
5. Vector stats + embedding-model rotation detection (total / by-type / by-model counts, clear-all utility).

46 methods annotated with @spec across 7 files:

• lib/Service/VectorizationService.php (10)
• lib/Service/Vectorization/VectorEmbeddings.php (10)
• lib/Service/Vectorization/Handlers/EmbeddingGeneratorHandler.php (5)
• lib/Service/Vectorization/Handlers/VectorStorageHandler.php (6)
• lib/Service/Vectorization/Handlers/VectorStatsHandler.php (4)
• lib/Service/Vectorization/Strategies/VectorizationStrategyInterface.php (4)
• lib/Service/Vectorization/Strategies/ObjectVectorizationStrategy.php (7)

Deferred

• The 4 delegating facade query methods (VectorizationService::semanticSearch/::hybridSearch, VectorEmbeddings::semanticSearch/::hybridSearch) are intentionally not annotated here — they generate the query embedding (covered by REQ-001) then delegate KNN execution to VectorSearchHandler, which the search capability already owns. They will be @spec-annotated against search/spec.md once PR retrofit: reverse-spec search partial (5 REQs / 37 methods, 111 deferred) #1791 lands.
• A FileVectorizationStrategy (chunk handling) is a future sixth REQ once the class lands.

Test plan

• php -l clean on all 7 touched files
• Annotation count matches tasks.md exactly (12/8/9/7/10 per task = 46)
• No deferred semanticSearch/hybridSearch methods annotated

[github-actions]

Quality Report — ConductionNL/openregister @ 6bf9f5b

Check	PHP	Vue	Security	License	Tests
lint	✅
phpcs	❌
phpmd	✅
psalm	✅
phpstan	✅
phpmetrics	✅
eslint		❌
stylelint		❌
composer			✅	✅ 162/162
npm			✅	✅ 532/532
PHPUnit					⏭️
Newman					⏭️
Playwright					⏭️

---

Quality workflow — 2026-05-25 06:12 UTC

Download the full PDF report from the workflow artifacts.