Preferences¶
Preferences tell Topos how an agent should trade off quality goals when a file
cannot reach IDEAL within the available iteration budget.
Topos measures four independent quality generators:
SIMPLE— low internal complexity.COMPOSABLE— bounded outward dependency burden.SECURE— no known dangerous calls or taint paths.NAVIGABLE— shallow nesting, cheap for an agent to read.
These generators form a sixteen-element lattice. IDEAL means all four are
satisfied, but the single-generator states are intentionally incomparable:
SIMPLE is not inherently better than SECURE, COMPOSABLE, or
NAVIGABLE. A preference ranking makes that tradeoff explicit.
What Preferences Do¶
preferences.ranking is a strict ordering of all four generators — a
three-element ranking written before v0.5.0 is no longer a valid permutation
and is rejected in favour of the default:
composable > secure > simple > navigable
This means: first try to satisfy all four generators. If that stalls, prefer
the best result that preserves COMPOSABLE and SECURE before spending
more effort on SIMPLE.
Topos turns the ranking into a total order over lattice verdicts by weighting
the ranked generators 8 / 4 / 2 / 1 — each weight exceeds all the lower
ones combined, making the order strictly lexicographic. With:
simple > navigable > secure > composable
which is the default ranking, the induced order is:
Verdict |
Score |
Meaning |
|---|---|---|
|
|
all four generators satisfied |
|
|
concedes only the last-ranked generator |
|
|
|
|
|
fallback target if |
|
|
|
|
|
|
|
|
|
|
|
keeps the top preference only |
|
|
satisfies the lower three preferences |
|
|
|
|
|
|
|
|
keeps the second preference only |
|
|
|
|
|
keeps the third preference only |
|
|
keeps the last preference only |
|
|
no generator satisfied |
Changed in version 0.5.0: The fallback target is no longer the element directly below IDEAL.
With three generators, “meet of the top two” and “one step below
IDEAL” were the same verdict; with four they differ. One step below
IDEAL concedes only the lowest-ranked generator
(SIMPLE_SECURE_NAVIGABLE above); the fallback concedes the bottom
two.
Changed in version 0.5.0: The default ranking is simple > navigable > secure > composable. The
two pillars an agent can always compute and always fix inside one file
rank highest; COMPOSABLE ranks last because it needs an external
dependency graph and describes a module’s place in the whole project,
so it is the right thing to concede first when coupling data is absent.
The important behavior is the fallback target: when IDEAL plateaus, the
agent should aim for the meet of the top two ranked generators.
Ranking |
First target |
Fallback target |
|---|---|---|
|
|
|
|
|
|
|
|
|
How Agents Use Preferences¶
When an agent evaluates a file with preferences, Topos returns a
preference_walk. The walk gives the agent a concrete sequence of targets:
Edit
next_pillar(the closest failing gate) while the goal isIDEAL.If that gate score does not move, divert to
fallback_targetand recompute.If that still stalls, follow
next_stepdown the preference order.
For example, with:
ranking = simple > navigable > secure > composable
current = SECURE
Topos can return:
target = IDEAL
fallback_target = SIMPLE_NAVIGABLE
next_step = COMPOSABLE_SECURE
next_pillar = the missing pillar of IDEAL with the greatest gate score below 0.5
next_step is the smallest verdict above the current one in the preference
order (the concession). next_pillar is the edit.
How to Set Preferences¶
For a one-off CLI evaluation, pass the complete ranking as a comma-separated
value. Persist project defaults with topos config:
topos evaluate src/ -r --priority composable,secure,simple,navigable
topos config set --priority composable,secure,simple,navigable
In MCP tools, pass preferences.ranking:
{
"filepath": "src/server.rs",
"preferences": {
"ranking": ["composable", "secure", "simple", "navigable"]
}
}
Use composable,secure,simple,navigable for library surfaces where coupling matters
most. Use secure,simple,navigable,composable for files handling untrusted
input. Use simple,navigable,secure,composable for leaf implementation files
where local complexity is the main source of drag.
Preferences vs. Priority¶
Preferences and priority are related, but they are not the same thing.
priorityThe head of the ranking. It wins an ascent tie. Pass/fail uses fixed raw gates and does not change with priority. Priority does not reweight scores.
preferences.rankingA full target-ordering contract. It ranks lattice verdicts, chooses
fallback_target, definesnext_step, and breaks ties innext_pillar.
Use the ranking when the agent needs a concession order. A single priority only names which generator wins when two gate scores match.