topos.evaluation.preferences

User preferences over the quality generators — induced order on Ω.

Priority (in topos.evaluation.policies.base) is a single upweighted generator: a knob on the policy translators Φᵢ. This module is a strictly stronger statement of the manager’s intent — a strict total order on the three generators:

g₁ ≻ g₂ ≻ g₃   with   {g₁, g₂, g₃} = G_qual

The lattice Ω = H(G_qual) is partially ordered (the three generator atoms are pairwise incomparable). A user preference linearizes it. We score each verdict v ∈ Ω by the satisfied-generator bitmask weighted by preference rank:

score(v) = Σᵢ 2^(n − i) · ⟦gᵢ satisfied by v⟧

So with the ranking (SIMPLE, COMPOSABLE, SECURE) (most → least):

IDEAL              = 4 + 2 + 1 = 7
SIMPLE_COMPOSABLE  = 4 + 2     = 6      ← default target ("ideal ∩")
SIMPLE_SECURE      = 4 + 1     = 5
SIMPLE             = 4
COMPOSABLE_SECURE  =     2 + 1 = 3
COMPOSABLE         =     2
SECURE             =         1
SLOP               = 0

The strict total order this induces refines Ω’s Heyting order: a ≤_H b ⟹ a ⪯_r b. Where the Heyting order leaves atoms incomparable, the preference order disambiguates.

Aspirational target + pragmatic fallback

The walk is two-stage:

1. Aspirational target — IDEAL. Agents first try to beat the policy thresholds for all three generators. Topos doesn’t assume IDEAL is unreachable a priori; some files genuinely satisfy every generator.

2. Pragmatic target (the “ideal intersection”) — the meet of the top-two ranked generators. If IDEAL stops moving after a few iterations, the agent diverts to this pairwise meet. For ranking (SIMPLE, COMPOSABLE, SECURE) the fallback is SIMPLE_COMPOSABLE; for (COMPOSABLE, SECURE, SIMPLE) it is COMPOSABLE_SECURE; etc.

Relaxation walk

relaxation_walk(prefs, current) returns the descending sequence of verdicts from IDEAL down to (but not including) the current verdict — the targeted relaxation walk. The agent uses it to pick the next achievable goal one step at a time; the pragmatic target sits exactly one step below IDEAL in the walk and is the natural divert-point when IDEAL plateaus.

class topos.evaluation.preferences.Generator(*values)

Bases: StrEnum

The three quality generators of G_qual.

SIMPLE = 'simple'

COMPOSABLE = 'composable'

SECURE = 'secure'

class topos.evaluation.preferences.UserPreferences(ranking, target=None)

Bases: object

A strict total order on G_qual.

ranking

Three distinct generators, most-preferred first.

Type:

tuple[topos.evaluation.preferences.Generator, topos.evaluation.preferences.Generator, topos.evaluation.preferences.Generator]

target

Optional explicit aspirational target verdict. Defaults to IDEAL — the agent first tries to beat the policy thresholds for all three generators. When IDEAL plateaus, fallback_target (the meet of the top-two ranked generators) is the natural divert point.

Type:

topos.core.omega.EvaluationValue | None

ranking

target = None

classmethod from_iterable(ranking, *, target=None)

score(value)

Lex-weighted preference score for a verdict.

Higher is more preferred. Weights are 4 / 2 / 1 across the ranking so the top-ranked generator dominates the next two combined — strictly lexicographic on the satisfied-generator bits in preference order.

induced_total_order()

All 8 verdicts sorted by descending preference.

aspirational_target()

The first target the agent should attempt.

Defaults to IDEAL (beat the policy thresholds for all three generators). Override via the target field if the caller knows a priori that IDEAL is unreachable for this codebase.

fallback_target()

The pragmatic divert-point if IDEAL plateaus.

This is the meet of the top-two ranked generators — what we call the “ideal intersection”. For ranking (COMPOSABLE, SECURE, SIMPLE) this is COMPOSABLE_SECURE; for (SIMPLE, COMPOSABLE, SECURE) it is SIMPLE_COMPOSABLE.

resolved_target()

relaxation_walk(current=None)

Descending walk from the aspirational target toward current.

Returned in descending preference order starting at the aspirational target (default: IDEAL) and ending one step above current. The second element of the walk is the fallback_target — the natural divert-point when IDEAL proves unreachable.

Empty when current already meets or exceeds the target.

next_step(current)

The immediate next achievable verdict above current.

Bottom of the relaxation walk — the smallest improvement that still respects the preference order. None when at or beyond the aspirational target.

progress(current)

Fractional progress from SLOP to the aspirational target.

Returns a value in [0.0, 1.0]. Reaches 1.0 exactly at the target verdict.

topos.evaluation.preferences.default_preferences()

Conservative default: SIMPLE ≻ COMPOSABLE ≻ SECURE.

Simplicity comes first (the cheapest property to verify and currently our strongest measure), then composability (the most cross-cutting and the only one requiring an external dep graph), then security.