Unsafe Review

Unsafe code is allowed only for architecture-specific vector kernels, PostgreSQL FFI, pgrx/PostgreSQL allocation contracts, buffer/page access, and validated artifact mappings where a safe Rust API cannot express the boundary. Every unsafe block in context-core, context-pg, and context-storage must have a nearby SAFETY: comment that states the caller contract, pointer ownership, lifetime, alignment, initialization, and cleanup reasoning that makes the block valid.

Checklist

Before release or any unsafe change:

  • run scripts/check-unsafe-safety-comments.sh;
  • run scripts/check-hnsw-callback-guards.sh and its adversarial shell smoke suite when HNSW callback or routine wiring changes;
  • confirm each unsafe extern callback documents the PostgreSQL caller contract and does not unwind across a non-unwind ABI;
  • confirm every raw pointer dereference has a live owner, non-null expectation, and lifetime bounded to the PostgreSQL callback or validated byte slice;
  • confirm PostgreSQL memory allocated through pgrx is returned to PostgreSQL or dropped exactly once;
  • confirm page, tuple, and mmap byte reads use validated lengths and alignment checks before interpreting bytes;
  • confirm SQL-visible failures map to typed diagnostics instead of panics;
  • run the narrow unit/property/fuzz/heavy tests that exercise the boundary.

Current Review

context-core isolates AArch64 NEON loads in metric_kernels; complete-chunk bounds and scalar-tail tests cover non-multiple-of-four dimensions.

context-storage owns its read-only OS mapping in mmap_file. Construction checks the file size and mapping result, validates the mapped header, payload bounds, alignment, and checksum before exposing a borrow, and unmaps the exact owned range once in Drop. Segment regression tests, property tests, and the segment_loader fuzz target cover header length, payload length, checksum, version, endian, and corruption cases. The practical Miri gate is:

cargo +nightly miri test -p context-storage

context-pg uses unsafe code for PostgreSQL extension and index access-method FFI, mainly in hnsw_am.rs. The current review requires local SAFETY: comments for unsafe blocks plus pgrx and heavy tests that cover HNSW build, insert, scan, vacuum, crash/restart, and corruption paths. Miri is not practical for PostgreSQL backend FFI, so sanitizer coverage should run through pgrx on a nightly toolchain when changing those callbacks:

The HNSW access-method entrypoints, safe functions, borrowed-input contracts, and retention rules are enumerated in the HNSW Callback Boundary Contract. Review that inventory whenever the routine gains, removes, or changes a callback.

RUSTFLAGS="-Zsanitizer=address" cargo +nightly pgrx test -p context-pg pg17

If sanitizer or Miri cannot run in the local environment, record the toolchain or platform blocker in the release report and run the gate in CI or on the release host before declaring the release candidate complete.

The executable hardening manifest keeps those commands, their owners, and the static unsafe guards in one fixed order. Product-build work should inspect it without starting a long campaign:

scripts/run-unsafe-hardening-report.sh --pg-major 17 --plan
scripts/run-unsafe-hardening-report.sh --pg-major 17 --dry-run \
  --out-dir target/unsafe-hardening/dry-run
tests/shell/run_unsafe_hardening_report_smoke.sh

--plan is side-effect free and emits the canonical TSV rows. --dry-run writes the same five rows and per-row logs without invoking Cargo, Miri, sanitizers, or PostgreSQL. The no-flag form executes every row and is owned by the frozen-SHA hardening phase. When a later product slice adds an unsafe owner, validated mmap view, callback surface, or subprocess harness, extend the runner and its smoke fixture in that same slice; do not defer the executable row until release evidence collection.