feat(#162): hnsw_export halfvec 지원 — dim 상한 문제 해결

[ysys143]

Summary

• Closes feat: hnsw_import halfvec 지원 — dim=3072 경로 부재 + 1024/1536 인덱스 2~3배 #162
• CAGRA GPU 빌드는 fp32 그대로 두고(cuVS는 fp16 CAGRA 미지원, ADR-054), write_elem_page()의 마지막 memcpy에서만 halfvec으로 narrow-cast — float_to_half()는 손수 구현한 IEEE-754 round-to-nearest-even이며 라이브 pgvector 0.8.6과 335/335 비트 단위 일치 검증(round-to-even tie 케이스 포함).
• halfvec_{l2,ip,cosine}_ops 3종 opclass를 pg_cuvs_hnsw AM에 등록(0.8.0, SQL-visible 신규 표면이라 마이너 범프).
• dim 상한 체크(check_hnsw_page_fit)를 GPU 작업 전으로 당겨 고정 safe_maxlevel=5로 조기 거부 — 기존엔 CAGRA 빌드+hnswlib 파일 생성이 끝난 뒤에야 거부돼 GPU 시간을 낭비했다.
• 이제 halfvec 경유로 dim=3072(vector HNSW 상한 2000으로는 도달 불가)까지 인덱싱 가능.

Commits (Tidy First: 구조 → 동작 → 동작 → 테스트)

1. refactor: elem_tuple_size/write_elem_page를 bytes_per_dim으로 파라미터화 (동작 불변)
2. feat: halfvec 쓰기 경로 + 카탈로그 타입 판별 + opclass SQL + 버전 핀 (0.8.0)
3. feat: dim 상한 체크를 GPU 작업 전으로 이동
4. test: halfvec 커버리지 — 신규 build_hnsw_halfvec.sql, dim 상한 거부 케이스, AM 경로 halfvec 케이스

Test plan

• make gpu-deploy → make gpu-verify-deployed (6항목 전부 GREEN)
• make installcheck 40/40 GREEN, 2회 연속 재현으로 안정성 확인(신규 테스트에 OID 플레이키니스 없음)
• make installcheck-isolation 6/6 GREEN
• float_to_half() 335/335 라이브 pgvector 0.8.6 대비 비트 단위 일치 (round-to-even tie 케이스 포함)
• 수기 스모크: dim=8/18벡터, mode=nsw·hnswlib 양쪽 — 검색 정합성 + 재빌드 결정성
• dim=1900(fp32,M=32)·dim=3600(halfvec,M=32) 사전 거부가 GPU/IPC 왕복 전에 발생함을 daemon 로그로 확인
• recall 측정(fp32 vs halfvec, dim=1536/3072, wiki_all_1M self-concatenation 재사용) — 별도 후속 커밋으로 진행 예정

[ysys143]

적대적 코드 리뷰(에이전트) 결과 및 대응 — 마지막 커밋(04c2f35)에 전부 반영:

HIGH — 실제 회귀, 수정함

• safe_maxlevel=5 사전 체크가 mode를 무시해 mode='nsw'(기본값)의 fp32 dim 1679~1918 구간을 잘못 거부. mode='nsw'는 실제로 max_level이 항상 0이므로 이제 정확한 경계(maxlevel=0)를 쓰고, 다른 모드는 기존 보수적 5를 유지. 회귀 가드 테스트 추가(dim=1900/mode='nsw' 성공 확인).
• TypenameGetTypid() 기반 타입 판별이 search_path에 의존해 제한된 search_path에서 평범한 fp32 빌드까지 스퓨리어스 ERROR 가능성. OID→이름 역방향 조회로 교체해 의존성 제거.

MEDIUM — 수정함

• pg_cuvs_build_hnsw() 사전 체크가 cagra AM 검증보다 먼저 실행되던 순서 버그 — 명시적 relam 체크 추가.
• 0.8.0 SQL이 halfvec opclass를 무조건 설치해 pgvector<0.7.0에서 설치 자체가 실패 — README 최소 요구사항을 0.7.0+로 명시하고, 이제 도달 불가능해진 C 가드(require_halfvec_capable_pgvector)는 삭제.

LOW — 수정함

• check_hnsw_page_fit()에 dim<=0 가드 추가(랩어라운드 방지).
• BENCHMARK.md의 미검증 "두 번 재현" 문구 제거, mode-aware 수정 반영해 실측치 재측정·갱신.
• 잘못된 테스트 상호참조 주석 수정.

검증 안 됐다고 확인된 것들 (문제 없음)

• float_to_half() 손수 구현 — subnormal/carry/부호 경로 전부 IEEE-754와 일치 확인.
• syscache tuple lifetime — ReleaseSysCache 순서 정확함(추가로 발견된 문제 없음).
• fresh 0.8.0 vs 0.7.0→0.8.0 업그레이드 카탈로그 동등성 — diff로 확인, 동일함.
• 잠금 누수 없음, ephemeral 경로의 M=32 가정 유효함(cuvs_wrapper.cu 확인).

VM 재검증: make installcheck 40/40, make installcheck-isolation 6/6, 두 번 연속 GREEN.