hive-milvus.collection.invariant — io.github.hive-agi/hive-milvus 0.4.4

THE DIMENSION INVARIANT: the width of the vector the embedder produces for a collection MUST equal the width that collection holds.

When it does not, nothing crashes. Milvus rejects an insert with error 1804, which a write path can swallow; and a SEARCH with a wrong-width query vector either errors or — the dangerous case, when another model happens to share the width — returns confident neighbours from a space the query was never embedded into. That is noise wearing the costume of an answer, and it is the shape the 2026-07-12 outage wore.

hive-milvus.store.search.boundary/CollectionEmbedder and hive-milvus.embedder/embed-for-entry already REFUSE to serve on a mismatch (:embedder/dim-mismatch) — read path and write path. That is the per-call half of the invariant, and it is the half that keeps a wrong vector out of the index.

This namespace is the OTHER half: assert it ONCE, at startup, so a misconfiguration is discovered when the server boots rather than on the first query of the day, silently, per call, forever.

Pure core / effectful shell: check — pure, one collection. violations — pure, a set of already-read (collection, expected, actual). verify — the boundary: reads live embedder dims, calls the pure core.

UNKNOWN IS NOT OK. naming/dim-of returns nil for a collection whose width is not knowable from its name (anything that is not a memory collection). Those are reported under :unknown — never folded into :ok. A checker that reports 'fine' when it means 'I could not tell' is the exact failure this file exists to prevent.

check clj

(check {:keys [collection expected actual]})

Pure. The invariant for ONE collection.

expected — the width the collection HOLDS (from its name, via naming/dim-of) actual — the width the embedder PRODUCES

=> r/ok {:collection … :dim n} aligned r/err :dim/unknown {:collection …} expected is unknowable r/err :dim/embedder-absent{:collection …} actual is unreadable r/err :embedder/dim-mismatch {:collection … :expected … :actual …}

The mismatch tag is deliberately the SAME keyword the per-call guards emit, so a startup report and a query refusal name the same fault.

read-dims clj

(read-dims collection-names)

BOUNDARY. For each collection name, pair the width it HOLDS (from its name) with the width its embedder PRODUCES (from the live provider registry).

An embedder that cannot be resolved reads as nil :actual — reported as :dim/embedder-absent, never skipped.

satisfied? clj

(satisfied? report)

Pure. True only when NOTHING is broken. :unknown does not break the invariant (a non-memory collection has no name-derivable width) but it never satisfies it either — it is simply out of scope for this check.

verify clj

(verify)

(verify collection-names)

BOUNDARY. The startup assertion. Reads the live widths and returns the violations report. Never throws.

0-arity checks every collection the embedding service has been configured with.

verify! clj

(verify!)

(verify! collection-names)

BOUNDARY. verify, but LOUD. Logs one ERROR per violation and one WARN per unverifiable collection, then returns the report so the caller can decide whether to refuse to start.

Call this from addon init. It does not throw: a violation must be visible in the log of a server that is still up (so an operator can read it) rather than turn a misconfigured embedder into a boot loop.

violations clj

(violations readings)

Pure. Partition already-read readings — a seq of {:collection … :expected … :actual …} — into the three buckets.

=> {:ok [{:collection :dim}…] :violations [err…] the invariant is BROKEN. Refuse to serve. :unknown [err…] the invariant is UNVERIFIABLE. Say so, loudly.}