core/docs/decisions/ADR-0001-vocab-layer-invariants.md

ADR-0001: VocabManifold Versor Invariant

Date: 2026-05-12
Status: Accepted
Commit: bd423e4

Context

VocabManifold stores word representations as multivectors in Cl(4,1). Without an enforced invariant, nothing prevented a caller from inserting a raw coordinate vector — a numpy array derived from an external embedding model, a lookup table, or any float array not constructed through the algebra — into the vocabulary. Such a vector would silently introduce an implicit Euclidean coordinate frame inside the vocabulary layer, undermining the entire field-state architecture.

This is a "back door" problem: the architecture is geometrically clean at every explicit boundary, but the vocabulary layer had no enforcement preventing external coordinate representations from entering through add().

Decision

Enforce the Cl(4,1) versor grade-norm condition at insertion time in VocabManifold.add():

grade_norm = float(geometric_product(v, reverse(v))[0])
if not (0.95 <= abs(grade_norm) <= 1.05):
    raise ValueError(...)

The scalar part of V * reverse(V) must be approximately ±1. This is the algebraic condition that distinguishes a valid Cl(4,1) versor from an arbitrary float array. Any raw embedding vector will fail this check.

Rationale

Serves Reality-over-Inheritance: governance is not a policy added later; it is a type-level contract enforced at construction. The vocabulary layer cannot be bypassed by a well-intentioned caller who "knows what they’re doing."

Serves Geometry-first: the first task is finding the intrinsic space. Once we’ve defined that space as Cl(4,1) with CGA structure, everything entering the vocabulary must live in that space by algebraic proof, not by convention.

Consequences

• Easier: Trust in the vocabulary is absolute. Any word returned by nearest() is guaranteed to be a valid CGA point. No defensive checks needed downstream.
• Harder: Callers must lift external representations through normalize_to_versor() before insertion. This is intentional friction.
• Forbidden: Inserting raw embedding vectors, cosine-similarity vectors, or any array not constructed through the algebra layer.

Alternatives Considered

• Soft warning instead of hard raise: Rejected. A warning that can be ignored is not an invariant.
• Normalize silently on insert: Rejected. Silent normalization hides the fact that the caller passed something invalid. The error message is the documentation at the point of failure.