# PostgreSQL Integration Module Organization

`context-pg` owns every PostgreSQL-specific concern: SQL objects, SPI access,
catalog hydration, ACL/RLS checks, pgrx conversion, SQLSTATE translation, index
access-method callbacks, and PostgreSQL-backed tests. This makes it the largest
workspace crate, but its dependency direction remains correct: reusable types
and algorithms stay in the pure crates and `context-pg` adapts them.

`context-pg` is decomposed into the private boundaries below:

| Owner | Responsibilities | Existing boundary | Decision |
|---|---|---|---|
| `hnsw_hierarchy` | hierarchical graph construction and search | graph mutation/search implementation is isolated in `graph_impl` | Keep the pure hierarchy owner while separating its implementation-heavy graph operations. |
| `artifact_segments` | publish, validate, list, retire, and reclaim rebuildable artifacts | diagnostics, serving readiness, SPI persistence, result conversion, and file cleanup are separate submodules or private include fragments | Keep one transactional owner; its operations share catalog locks and lifecycle invariants. |
| `table_search` | registered-table exact search, scroll, count, facets, and source visibility | catalog access, candidate recheck, grouped search, named search, recommendations, and shared support are submodules | Keep the facade; isolated search strategies remain behind explicit private boundaries. |
| `build_jobs` | build-job lifecycle and authoritative source scanning | backend identity, job types, validation, and SPI persistence are separate private fragments | Keep one lifecycle owner so status transitions and catalog writes cannot drift. |
| `vector_catalog` | dense and sparse vector registration/configuration | SPI persistence and catalog hydration are isolated from the SQL-facing facade | Keep one catalog owner until dense and sparse catalogs gain independently changing contracts. |
| `operations` | index status, diagnostics, memory estimates, optimization, vacuum advice, and recall checks | advisor logic and checked catalog/value helpers are private fragments | Keep one operator-facing diagnostics facade while centralizing checked conversions. |
| `hnsw_am` | access-method registration, callback routing, scan state, persisted pages, and validation | SQL declarations, callback, FFI, bitmap, options, codec, storage, vacuum, WAL, and MVCC concerns are isolated | Keep one PostgreSQL AM owner; SQL dependencies and unsafe callback invariants are independently reviewable. |
| `vector_variants` | PostgreSQL types, casts, distance functions, and aggregates for half, sparse, and bit vectors | aggregate finalization helpers are isolated; exact kernels remain in `context-core` | Keep the SQL type facade; do not duplicate exact metric semantics here. |

No additional crate is justified by this review. A future split requires at
least one concrete trigger: a different dependency surface, an independently
published contract, a distinct team owner, or a reusable pure component that
can be tested without PostgreSQL. File length alone is not a crate boundary.

The mechanical guard is `scripts/check-source-hygiene.sh`: Rust files over the
review threshold must have a pinned maximum and cannot silently grow. The
architectural guard is `scripts/check-crate-boundaries.sh`, which prevents
PostgreSQL and transport concerns from leaking into pure crates.