feat(u7): filename groups — the last v1 unit, and a table that did not reproduce

Completes U7 with its fourth component: a jump-to-group rail derived from filename prefixes, replacing the subfolder sections ROADMAP named. The scope departure was ratified by the operator 2026-09-22; this commit deletes test_no_group_rail_is_shipped_yet, the guard that held it back, in the same change that builds what it guarded against. All seven v1 capabilities are now landed. The 1.0 cut is a decision, not a dependency, and it is the operator's — no version bump here, because a commit is not a release. THE RULE CHANGED AT IMPLEMENTATION, ON MEASURED GROUNDS. The contract specified `strip ONE trailing run of digits`; run against the live set that yields 24 groups for sindra-bakeoff's 40 images and 27 for sindra's 30 — a rail with a row per tile — because it keys on the END of the stem, where the instance number lives. The contract's own table claimed 5 and 1 for those two booths and neither reproduces; the numbers are reachable only by two OTHER heuristics, so the table that justified the design was assembled from more than one rule. Its own worked example contradicts it in plain sight. The shipped rule keys on the first separator-delimited segment, where the family lives, destemming only when the stem has no separator at all — so `ac01` -> `ac` while `v30-seed8302` and `v35-seed8302` stay apart. Re-measured across all 17 live booths; the table is in the contract. INV-3 GAINED ITS SECOND DEGENERACY. The contract guarded one group for everything (sc-iso-spread: DSC0001-DSC0006). The live set's actual failure is the opposite — pewpew-ui-brief yields 23 groups for 34 items, dfa-concepts 13 for 20 — and the contract as written would have shipped a rail that is a second copy of the grid. The rail now renders only when grouping is informative: two or more groups, and the middle group holding more than one item. That predicate gets all 17 booths right. Grouping is a VIEW. The grid stays sorted(rel) and the zoom ring stays that order filtered to images; the group fixture interleaves across subdirectories precisely so a (group, rel) re-sort goes red. Groups are derived from the RENDERED list, not the full gallery, so no anchor points at a filtered-out tile. booth/items.py _group_of + Item.group, derived in the resolver (INV-1) booth/app.py _groups() builds the rail rows; build_gallery carries it booth/templates/ the rail-groups nav and its CSS tests/ +16 tests; 639 green Every new falsifier was proved by running its defeating change (12/12). Three were vacuous first time out: one fixture's positional order happened to be alphabetical, one assertion miscounted elements, and the harness itself certified a broken test twice — no green baseline, and byte-identical mutations silently defeated by the pyc cache's one-second mtime granularity.
2026-09-22 21:33:54 -07:00
parent 2f85692e95
commit bf351a26d1
11 changed files with 697 additions and 86 deletions
@@ -258,3 +258,61 @@ def test_list_booths_counts_match_the_resolver(tmp_path):

    got = list_booths(tmp_path, ttl_seconds=86400)[0]
    assert got["count"] == len(booth_items(b)) == 2
+
+
+# --- U7: the group, derived here and nowhere else -------------------------
+#
+# ⚠ THE RULE IS NOT THE ONE THE CONTRACT FIRST STATED, and the change is
+# measured rather than preferred. The contract's `strip ONE trailing run of
+# digits` yields 24 groups for sindra-bakeoff's 40 images and 27 for sindra's
+# 30 — a rail with one row per tile, which is a second copy of the grid rather
+# than a way through it. Measured against all 17 live booths on 2026-09-22;
+# the numbers are in the contract's rewritten table.
+
+
+def test_group_of_takes_the_first_segment(tmp_path):
+    from booth.items import _group_of
+
+    assert _group_of("00-sheet-c1-market-noon.png") == "00"
+    assert _group_of("m-c1-market-noon-9401.png") == "m"
+    assert _group_of("flag-rear.png") == "flag"
+    assert _group_of("v30-seed8302-HELD.png") == "v30"
+
+
+def test_group_of_destems_only_a_flat_name(tmp_path):
+    """`ac01.png` has no separator, so the digits ARE the separator and the
+    group is `ac`. `v30-seed8302` HAS one, so `v30` survives intact — stripping
+    there would merge v30 with v35, which is the axis that booth is about."""
+    from booth.items import _group_of
+
+    assert _group_of("ac01.png") == "ac"
+    assert _group_of("DSC0001.jpg") == "DSC"
+    assert _group_of("v30-seed8302.png") == "v30"
+    assert _group_of("v35-seed8302.png") == "v35"
+
+
+def test_group_of_is_none_when_there_is_no_prefix(tmp_path):
+    """A stem that is entirely digits has nothing to group on. Inventing one
+    would file every numbered render under the empty string."""
+    from booth.items import _group_of
+
+    assert _group_of("01.png") is None
+    assert _group_of("0042.jpg") is None
+    assert _group_of("-leading.png") is None
+
+
+def test_group_is_derived_from_the_basename_not_the_path(tmp_path):
+    """A booth WITH subdirectories still groups on the filename. Sections and
+    groups are different questions; `Item.section` still carries the path."""
+    from booth.items import _group_of
+
+    assert _group_of("sub/dir/ac01.png") == "ac"
+
+
+def test_booth_items_carries_the_group(tmp_path):
+    b = tmp_path / "g"
+    _touch(b / "ac01.png")
+    _touch(b / "ac02.png")
+    _touch(b / "99.png")
+    got = {it.rel: it.group for it in booth_items(b)}
+    assert got == {"ac01.png": "ac", "ac02.png": "ac", "99.png": None}
@@ -1,11 +1,11 @@
-"""U7 slice 1 — the rail, the filters, the grid keyboard.
+"""U7 — the rail, the filters, the grid keyboard, and the groups.

-⚠ SCOPE. This covers ONLY the three components ROADMAP's U7 row already
-ratifies: a sticky rail, filters, and grid keyboard. The fourth — replacing
-directory sections with filename-derived groups — is a scope DEPARTURE proposed
-in `docs/contracts/u7_navigation.contract.md` and is deliberately NOT built
-here, because it is the operator's call and he has not made it. The rail
-therefore carries totals and filter counts and no jump-to-group anchors yet.
+All four components. The fourth — replacing directory sections with
+filename-derived groups — was a scope DEPARTURE from ROADMAP's U7 row and was
+ratified by the operator on 2026-09-22; `test_no_group_rail_is_shipped_yet`,
+the guard that held it back while the ruling was outstanding, was deleted in
+the commit that built it. A guard that outlives its reason is worse than no
+guard, because the next reader trusts it.

 `unanswered` is taken to mean HAS AN OPEN PICK — the U4 hold predicate, which
 already exists and already has a home. The alternative reading ("has no mark at
@@ -158,13 +158,247 @@ def test_the_keyboard_is_bound_when_there_is_one(gallery):
    assert "gridkeys" in c.get("/b/g/").text


-def test_no_group_rail_is_shipped_yet(gallery):
-    """⚠ SCOPE GUARD, and it is deliberate. Replacing directory sections with
-    filename-derived groups is a scope DEPARTURE from ROADMAP's U7 row that the
-    operator has not ruled on. This test fails the moment somebody builds it
-    anyway, so the departure cannot arrive by accident while he is away."""
+
+
+# --- U7 slice 2: the groups ----------------------------------------------
+
+
+@pytest.fixture
+def grouped(tmp_path):
+    """Two groups whose members INTERLEAVE in `sorted(rel)`.
+
+    `a/x1.png, a/y1.png, b/x2.png, b/y2.png` is the sorted order; group `x` is
+    at positions 0 and 2, group `y` at 1 and 3. That interleaving is the whole
+    point of the fixture — a grid re-sorted by `(group, rel)` to make groups
+    render contiguously would pass every set-based assertion and fail these.
+    """
+    b = tmp_path / "g"
+    for rel in ("a/x1.png", "a/y1.png", "b/x2.png", "b/y2.png"):
+        p = b / rel
+        p.parent.mkdir(parents=True, exist_ok=True)
+        p.write_bytes(PNG)
+    app = create_app(tmp_path, ttl_hours=24, start_sweeper=False)
+    return TestClient(app), b
+
+
+def _groups(body: str) -> list[str]:
+    """The group keys the rail listed, in render order."""
+    import re
+    return re.findall(r'data-group="([^"]+)"', body)
+
+
+def test_the_rail_lists_groups_when_grouping_is_informative(grouped):
+    c, _ = grouped
+    body = c.get("/b/g/").text
+    assert 'class="rail-groups"' in body
+    assert _groups(body) == ["x", "y"]
+
+
+def test_group_order_is_the_position_of_the_first_member(tmp_path):
+    """The settled rule (ROADMAP, operator 2026-09-22): groups order by where
+    each group's FIRST member falls in the rendered sequence.
+
+    ⚠ THIS FIXTURE IS BUILT SO THE THREE PLAUSIBLE RULES ALL DISAGREE. The
+    first version used `w, x, y` — whose positional order happens to BE
+    alphabetical, so it stayed green under the very change it forbade. Caught
+    by running the mutation, not by reading the assertion; the same trap
+    persistent-memory.d/2026-09-22-vacuous-falsifiers.md names and the same one
+    `test_filtering_never_reorders` fell into an hour after it was written.
+
+        sorted(rel):  a/z1  a/z2  b/a1  b/a2  b/a3  c/m1  c/m2
+        by position:  z (0), a (2), m (5)      <- the rule
+        alphabetical: a, m, z                  <- wrong, and differs
+        by count:     a(3), z(2), m(2)         <- wrong, and differs
+    """
+    b = tmp_path / "g"
+    for rel in ("a/z1.png", "a/z2.png", "b/a1.png", "b/a2.png", "b/a3.png",
+                "c/m1.png", "c/m2.png"):
+        q = b / rel
+        q.parent.mkdir(parents=True, exist_ok=True)
+        q.write_bytes(PNG)
+    c = TestClient(create_app(tmp_path, ttl_hours=24, start_sweeper=False))
+    assert _groups(c.get("/b/g/").text) == ["z", "a", "m"]
+
+
+def test_grouping_never_reorders_the_grid(grouped):
+    """INV-2, the load-bearing one.
+
+    The defeating change is sorting the grid by `(group, rel)` so groups render
+    contiguously — which looks right, passes any set comparison, and silently
+    changes what "the third one" means. This fixture interleaves precisely so
+    that change goes red.
+
+    The baseline is INDEPENDENT (U1 INV-3: the order IS `sorted(rel)`), not a
+    second response — the vacuous-falsifier trap this suite already fell into
+    once."""
+    c, _ = grouped
+    tiles = _tiles(c.get("/b/g/").text)
+    assert tiles == ["a/x1.png", "a/y1.png", "b/x2.png", "b/y2.png"]
+    assert tiles == sorted(tiles)
+
+
+def test_every_group_anchor_lands_on_a_rendered_tile(grouped):
+    """A jump-to-group link that scrolls nowhere is worse than no link. Every
+    anchor must name an id the page actually carries.
+
+    Defeating change: anchoring to the group KEY (`#group-x`) while the tiles
+    carry `id="item-<rel>"` — which renders, looks right, and does nothing."""
+    import re
+    c, _ = grouped
+    body = c.get("/b/g/").text
+    hrefs = re.findall(r'class="rail-g"[^>]*href="#([^"]+)"', body)
+    assert hrefs, "the rail rendered no group anchors"
+    for h in hrefs:
+        assert f'id="{h}"' in body, f"anchor #{h} names no element on the page"
+
+
+def test_no_group_rail_when_every_item_is_its_own_group(gallery):
+    """INV-3's real failure mode, and it is NOT the one the contract feared.
+
+    `a.png b.png c.png d.png` yields four groups of one — a rail that is a
+    second copy of the grid. Measured live: `pewpew-ui-brief` gives 23 groups
+    for 34 items, `dfa-concepts` 13 for 20. The contract only guarded the
+    opposite degeneracy (one group for everything), which is why this test
+    exists.
+
+    Defeating change: `{% if rail.groups %}`, true for four singletons."""
    c, _ = gallery
    body = c.get("/b/g/").text
-    assert "data-group" not in body
    assert 'class="rail-groups"' not in body
-    assert 'class="rail"' in body, "the approved rail must still be here"
+    assert 'class="rail"' in body, "the filter rail must still be here"
+
+
+def test_no_group_rail_when_there_is_only_one_group(tmp_path):
+    """INV-3 as the contract states it, with the live specimen: `sc-iso-spread`
+    is `DSC0001.jpg` through `DSC0006.jpg` — one group, six images.
+
+    Defeating change: `{% if rail.groups %}`, true for a single group."""
+    b = tmp_path / "flat"
+    b.mkdir()
+    for i in range(1, 7):
+        (b / f"DSC{i:04d}.jpg").write_bytes(PNG)
+    c = TestClient(create_app(tmp_path, ttl_hours=24, start_sweeper=False))
+    body = c.get("/b/flat/").text
+    assert 'class="rail-groups"' not in body
+    assert 'class="rail"' in body
+
+
+def test_groups_describe_the_filtered_grid(tmp_path):
+    """The rail describes what is ON SCREEN. An anchor to a group the filter
+    has hidden would scroll nowhere — the same defect as a wrong id, arriving
+    by a different route.
+
+    Three groups of two; the flag covers `x` and `y` entirely and `z` not at
+    all. Under `?filter=flagged` the rail must list x and y and MUST NOT list
+    z, whose two tiles are not on the page.
+
+    Defeating change: deriving groups from the full gallery rather than from
+    the rendered list — under which `z` appears and its anchor goes nowhere."""
+    b = tmp_path / "g"
+    b.mkdir()
+    for n in ("x1.png", "x2.png", "y1.png", "y2.png", "z1.png", "z2.png"):
+        (b / n).write_bytes(PNG)
+    for n in ("x1.png", "x2.png", "y1.png", "y2.png"):
+        set_flag(b, n, True)
+    c = TestClient(create_app(tmp_path, ttl_hours=24, start_sweeper=False))
+
+    assert _groups(c.get("/b/g/").text) == ["x", "y", "z"]
+    body = c.get("/b/g/?filter=flagged").text
+    assert _groups(body) == ["x", "y"]
+    assert _tiles(body) == ["x1.png", "x2.png", "y1.png", "y2.png"]
+
+
+def test_a_filtered_view_too_small_to_group_drops_the_group_row(grouped):
+    """The informativeness rule binds to the RENDERED list, not to the booth.
+
+    One flagged tile is one group of one, which cannot navigate — so the group
+    row goes away even though the unfiltered booth has a perfectly good one.
+    The filter rail stays, because that is how the operator gets back."""
+    c, b = grouped
+    set_flag(b, "a/x1.png", True)
+    assert 'class="rail-groups"' in c.get("/b/g/").text
+    body = c.get("/b/g/?filter=flagged").text
+    assert 'class="rail-groups"' not in body
+    assert 'class="rail"' in body
+
+
+def test_the_zoom_ring_ignores_grouping(grouped):
+    """The ring is `sorted(rel)` filtered to images and must not notice groups
+    any more than it notices filters.
+
+    THE FIXTURE IS THE FALSIFIER. From `a/x1.png`, sorted order says next is
+    `a/y1.png` — a DIFFERENT group. A ring rebuilt per group would say
+    `b/x2.png`, the next member of group `x`, and `→` would start walking a
+    sequence the operator never saw on the page. That is invariant 6's
+    misfiled-judgment failure exactly: the flag lands on the wrong artifact."""
+    import re
+    c, _ = grouped
+    body = c.get("/b/g/view?f=a/x1.png").text
+    nxt = re.findall(r'class="vnav vnext" href="\?f=([^"&]+)"', body)
+    assert nxt == ["a/y1.png"], f"the ring followed the group, not sorted(rel): {nxt}"
+    # and the zoom page has no group chrome at all — it is one artifact, not a wall
+    assert "data-group" not in body
+
+
+def test_no_route_body_derives_a_group(gallery):
+    """INV-1, the same assertion U1 makes for `classify` and `render_doc`.
+
+    Defeating change: a route or template computing a prefix inline — the
+    caption bug in a new field."""
+    import inspect
+
+    import booth.app as app_mod
+
+    src = inspect.getsource(app_mod.create_app)
+    assert "_group_of" not in src, "create_app must read Item.group, not derive it"
+
+
+def test_a_hostile_filename_cannot_break_out_of_the_rail(tmp_path):
+    """Group keys and anchors are AGENT-AUTHORED — they are filenames, and a
+    session makes a booth by making a folder with no validation anywhere in the
+    path. CLAUDE.md names autoescape as load-bearing for exactly this.
+
+    Defeating change: building the rail markup with `|safe`, or assembling the
+    href by string concatenation outside Jinja. Both render, both look right,
+    and both put attacker-controlled bytes into an attribute."""
+    b = tmp_path / "g"
+    b.mkdir()
+    for n in ('q"x1.png', 'q"x2.png', "s<script>1.png", "s<script>2.png"):
+        (b / n).write_bytes(PNG)
+    c = TestClient(create_app(tmp_path, ttl_hours=24, start_sweeper=False))
+    import re
+    r = c.get("/b/g/")
+    assert r.status_code == 200
+    body = r.text
+
+    # THE RAIL ITSELF, isolated — asserting over the whole page would pass on a
+    # booth where the escaping happened somewhere else.
+    nav = re.search(r'<nav class="rail-groups".*?</nav>', body, re.S)
+    assert nav, "the rail rendered no group row"
+    nav = nav.group(0)
+
+    # No tag the template did not write, and no attribute the filename closed.
+    # Asserted as the SET of element names rather than by counting `<`, which
+    # the first version got wrong by forgetting the `<b>` counts — an arithmetic
+    # slip that made the test red for a reason unrelated to escaping.
+    tags = set(re.findall(r"</?([a-zA-Z][a-zA-Z0-9]*)", nav))
+    assert tags == {"nav", "a", "b"}, f"the rail grew an element: {tags}"
+    assert 'data-group="q"' not in nav, "the quote closed the attribute"
+    assert "&lt;script&gt;" in nav and "<script" not in nav
+    assert "&#34;" in nav or "&quot;" in nav, "the quote was not escaped"
+
+
+def test_a_group_key_is_never_the_empty_string(tmp_path):
+    """`_group_of` returns None rather than "" for a stem with nothing before
+    the digits. A "" key would render a nameless rail row that files every
+    numbered render under it — the failure the None is there to prevent.
+
+    Defeating change: `return segs[0]` without the `or None`."""
+    b = tmp_path / "g"
+    b.mkdir()
+    for n in ("01.png", "02.png", "03.png", "ac1.png", "ac2.png"):
+        (b / n).write_bytes(PNG)
+    c = TestClient(create_app(tmp_path, ttl_hours=24, start_sweeper=False))
+    body = c.get("/b/g/").text
+    assert 'data-group=""' not in body
+    assert "" not in _groups(body)