Skip to content

guard(pattern): registries that floor themselves catch deletion and never addition #15904

Description

@mrveiss

A guard that holds a hardcoded registry and floors the registry rather than the tree catches an entry being deleted and can never catch one being added. Three instances, and in one of them the missing entry already existed.

guard registry floor catches
SLM publish contract (#15724) IMPLEMENTATIONS dict MIN_IMPLEMENTATIONS = 3 deletion only
man-page indexer delegation (#15902) two module constants — deletion only
ambient git-var scrub (#15893) was an enumeration now discovery both

The third is the control: it was converted to discovery — any shell file that unsets GIT_DIR is claiming to scrub, so it must scrub all six — and that conversion immediately found a seventh site the enumeration had missed.

Why a floor on the registry is not a floor

MIN_IMPLEMENTATIONS = 3 asserts the dict still has three entries. It is satisfied by the dict, which the test file owns and which no repository change can alter. It therefore measures nothing about the world it claims to describe: the population it floors and the population it is about are different sets.

This is the same defect as #15901's reference count — a number that cannot move in the direction the failure would move it — and the same as python_filter_covers_its_guards_test.py flooring detected reads while globs never enter the population (#15900).

The instance where it already cost something

#15724's registry keyed on the shell spelling of the atomic-flip idiom. A third implementation existed the whole time in services/slm_frontend_build.py, satisfying the same five clauses in Python via os.replace over a staged symlink. The guard reported a complete registry of two while three existed.

Enumeration there was not merely incomplete — it reported completeness. That is the property worth fixing: an incomplete check that is silent is a gap; one that returns a confident count is a false negative with evidence attached.

And completeness now rests on comments

In the same batch, the argument that the registry is complete depends on two callers (sync-frontend.sh, bootstrap-slm.sh) each carrying a comment stating it delegates rather than reimplements. Those comments are correct today.

But #15724's own finding, in that same batch, is that a comment survives the deletion of the thing it describes — a clause was satisfiable by prose documenting the idiom directly above the task performing it, and deleting the task while keeping the comment left every test green. So the completeness argument rests on exactly the artefact the batch proved unreliable.

Acceptance criteria

  • Each registry floors a discovered population, not its own literal — the count comes from sweeping the tree, so a new implementation fails on arrival rather than joining silently.
  • A legitimate delegator (a caller that invokes rather than reimplements) costs one deliberate line, not a silent pass. Discovery that cannot distinguish delegation from duplication will be muted, which is worse than enumeration.
  • Delegation is established by what the code does — it invokes the canonical entry point — never by a comment saying so. A comment cannot fail, and this batch is the proof.
  • Comments are stripped before matching wherever the match is about code, and not stripped where the assertion is that a pointer comment exists. That split is principled and already correct in guard(deploy): four deploy facts stated twice, now stated once and checked (#15707, #15724, #15687, #15604) #15901; it needs stating so a later edit does not collapse it.
  • The sweep reports what it examined — files swept, references found, references unresolvable — so a sweep collecting nothing fails loudly instead of reporting clean.

Note

The last criterion is not generic advice. #15901's _referenced_repo_paths silently dropped unresolvable references via continue, so its summary reported 1 resolves while 168 were unresolvable and invisible. Printing both changed a number that could not fail into one that can.

Registry instances found by Helper-01 reviewing #15901 and b9 reviewing #15895.

Refs #15724, #15902, #15893, #15900, #15901

Activity

  1. mrveiss commented on Sep 7, 2026

    @mrveiss
    OwnerAuthor

    Correction: one of the two instances is not an instance, and I filed it

    The SLM publish contract was listed here as "catches deletion only". That is wrong. It has both halves:

    slm_frontend_publish_contract.py:72        MIN_IMPLEMENTATIONS = 3      floors the dict
    slm_frontend_publish_contract_test.py:134  test_no_unlisted_publisher_exists
                                                 REPO_ROOT.rglob("*") over .sh/.yml/.yaml/.j2/.py,
                                                 matched against _PUBLISHER_HINTS,
                                                 with a reasoned _NOT_PUBLISHERS allowlist
    

    So an unlisted fourth implementation is caught — by a discovery sweep, not by the dict floor. The floor and the discovery are two tests doing two jobs: the floor catches the registry collapsing, the sweep catches the tree growing past it. That is the design this issue asks for, already present.

    I read MIN_IMPLEMENTATIONS flooring len(IMPLEMENTATIONS), recognised the shape from two real instances, and did not check whether a sibling test covered the other direction. The pattern was real and I stopped looking once the site matched it — which is this repository's most-repeated failure of the week, committed while cataloguing it.

    What survives

    site floors registry discovers verdict
    SLM publish contract (#15724) yes yes not an instance
    man-page indexer delegation (#15902) n/a no real instance
    ambient git-var scrub (#15893) n/a yes the control — conversion found a 7th site

    That leaves one live instance, and it already has its own issue. This issue is therefore close to a restatement of #15902 with a control attached.

    Recommendation

    Fold the durable content into #15902 and close this. What is worth keeping is not the instance list — it is the pair of properties, which the SLM guard demonstrates and the man-page guard lacks:

    • a floor bound to the registry catches the registry collapsing;
    • a discovery sweep catches the tree growing past the registry;
    • neither substitutes for the other, and a guard with only the first reports a complete set while an unlisted implementation exists.

    That framing survives the correction and is what #15902 should carry. The generic-pattern issue does not earn its own number on one instance.

    Leaving open pending that call rather than closing unilaterally, since #15902's author may want the properties stated there rather than referenced.

  2. modified the milestones: Backlog, v0.14.0 on Sep 12, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions