Concepts

Topos applies category theory and intuitionistic logic to code quality evaluation. You don’t need to understand the math to use Topos — this page explains the ideas behind the design.

The Evaluation Lattice

At the heart of Topos is a Heyting algebra of evaluation values. Unlike a simple pass/fail test, this algebra captures degrees of confidence about code quality.

The values form a partial order:

        graph BT
   INVALID["⊥ INVALID"]
   HALLUCINATED["○ HALLUCINATED"]
   NOISY["◑ NOISY"]
   WEAK["◒ WEAK"]
   COMMODITY["◐ COMMODITY"]
   VERIFIED["⊤ VERIFIED"]

   INVALID --> HALLUCINATED
   INVALID --> NOISY
   INVALID --> WEAK
   INVALID --> COMMODITY
   HALLUCINATED --> VERIFIED
   NOISY --> COMMODITY
   WEAK --> COMMODITY
   COMMODITY --> VERIFIED

This is a partial order, not a total order. NOISY and WEAK are incomparable — they represent qualitatively different concerns. A function might be branching-heavy (high complexity) but well-structured, or simple but repetitive. A partial order lets us track distinct failure modes without collapsing them onto a single axis.

When combining multiple metric evaluations, Topos uses meet (∧) — the greatest lower bound. The overall evaluation is only as good as the weakest signal, so no single metric can hide a problem revealed by another.

Programs as Morphisms

In category theory, a morphism is an arrow f: A → B that transforms objects. Topos views programs the same way: source code is a morphism that transforms inputs into outputs.

The ProgramMorphism class captures this:

from topos import ProgramMorphism

morphism = ProgramMorphism.from_file("transform.py")
print(morphism.ast.node_count)
print(morphism.ast.depth)

Two programs may compute the same function but have dramatically different internal structure. By modeling programs as morphisms and parsing their ASTs, Topos can reason about structural invariants that input-output testing cannot reveal.

The Subobject Classifier

In a Topos, the subobject classifier Ω is the object that answers membership questions. For any subobject S ⊆ X, there is a unique characteristic map χ: X → Ω that classifies membership.

In the category of Sets, Ω = {true, false}. In our Topos of Programs, Ω is the six-valued Heyting algebra, and χ captures degrees of membership in the class of well-structured code.

The SubobjectClassifier implements this map:

from topos import ProgramMorphism, SubobjectClassifier

morphism = ProgramMorphism.from_file("module.py")
result = SubobjectClassifier().classify(morphism)
print(result)  # e.g., "◐ COMMODITY"

The map factors through two stages:

  1. Metrics — extract complexity and entropy from the AST

  2. Policies — map metric values to evaluation values via threshold bins

  3. Aggregation — combine metric verdicts using lattice meet

This separates what we measure from how we interpret it, making the system transparent and extensible.