TD-131 Vector-Document Sync Investigation Report

Date: 2026-03-11 | Agent: Claude Code (Opus 4.6)

Root Cause

KHÔNG phải bug sync logic. Chuỗi CRUD → Vector hoạt động đúng qua API.

Vấn đề: S109 import script (import_firestore_to_pg.py) ghi trực tiếp SQL vào PG, bypass toàn bộ API layer → PG có 868 soft-deleted docs mà Qdrant không biết → 137 orphan vectors (497 - 360).

5 Câu trả lời

1. webhooks = 0: webhook_config.json có "active": false. ĐÚNG thiết kế — vector sync hardcoded trong CRUD, không qua webhook.
2. Health "ok" khi ratio=1.4: Threshold sai: ratio > 50 mới warning. 1.4 nằm trong "ok". Cần sửa: >1.1 warning, >1.3 critical.
3. DOT tools không phát hiện: dot-orphan-scan quét Directus registry, KHÔNG quét Qdrant. dot-selftest quét UI. Thiếu dot-vector-audit.
4. Chuỗi sync: create/update/delete_document() → _sync/_delete_vector_entry() → Qdrant. Trực tiếp trong code, không qua event system.
5. Gãy từ đâu: S109 import script bypass API. Không phải lỗi sync code.

Lỗ hổng giám sát phát hiện

• Health check threshold > 50 (vô nghĩa cho ratio nên ≈ 1.0)
• DOT tools không quét vector layer
• system_issues (CAT-017) không tự phát hiện vector drift
• Toàn bộ Tầng 5 giám sát CÓ LỖ HỔNG ở vector layer

Bài học

• KHÔNG BAO GIỜ ghi trực tiếp SQL bypass API → vector không đồng bộ
• Health check phải cảnh báo đúng: ratio > 1.1 warn, > 1.3 critical
• Cần DOT tool quét vector orphan (dot-vector-audit)
• Quy tắc đã thêm vào Operating Rules §9.3