Hadúr

Extending the lens registry

The lens registry ships with a default set — and it is an allowlist with a growth rule: a project may extend it; it may never shrink it. This guide covers when to add a lens, how to add one, and the two rules that protect the registry from its own success.

A lens is a question, not an area

Two reviewers can read the same file and return disjoint findings, because one asked "does this match the declared signature?" and the other asked "can hostile input from one side of this boundary corrupt the other?" (§7.3.1). Before adding a lens, write it as a question. If you can only name a directory, you have a review target, not a lens — targets belong in the brief, not the registry.

When to add: the free sweep found something

The registry grows by exactly one mechanism (§23): the free sweep — the one row with no assigned question — finds a defect that no named lens was ever going to find, and the question that would have found it becomes the next named lens. That is the free sweep's entire function: it is the port through which the methodology learns what it does not yet know to ask (§7.3.2).

You can also add lenses from outside experience — a domain your project has that the default registry does not cover (a payments boundary, a consent-tracking surface). The bar is the same: a question, falsifiable, re-askable by a third party.

How to add one

  1. Add the lens to your project's registry with an id, a name, and the question, stated so a third party can re-ask exactly it.
  2. Extend the findings-schema allowlist to accept the new id. In Hadúr the schema pins lens ids to the registry, so an invented id is a write-time schema error rather than a phantom lens that silently satisfies coverage — keep that property when you extend.
  3. Accept the cost knowingly: convergence requires two consecutive clean rounds in every lens (§7.3), so each new lens adds two dispatches to the end of every cycle. That is the price of the guarantee, and it is the point.

New-lens verdicts follow the same evidence rules as every other lens: a distinct reviewer identity per round, and a hash-pinned brief on disk that names the lens (§7.3.4). A lens without provenance counts for nothing.

The two rules that never bend

Never shrink. Removing a lens retroactively declares a blind spot covered. If the budget genuinely is not there, the honest move is to declare the cycle unconverged and name the lenses that were not run — not to trim the registry until the survivors come back clean. On the record this methodology is distilled from, the security lens ran for the first time in round 26 of 27 and found the worst defect in the suite.

Never sharpen the free sweep. A specific question is a welcome new lens — add it, and keep the free sweep unfocused. The moment the free sweep acquires a focus, the registry has closed, and a closed registry is a fail-open enumeration: a convergence check whose safety oracle is the list of mistakes already made (§6.5). The free sweep exists because the list is incomplete. It never closes; the site renders it with that badge for a reason.

The catalog parallel

The same growth-not-shrinkage discipline governs the drift catalog: its final class is the fail-open enumeration itself (§20), kept as the standing reminder that every enumeration — including a registry of review questions — is one element short. Extending a registry is how you spend that lesson; shrinking one is how you unlearn it.