feat(rules): a usage badge on the rule list, and the badge becomes canon instead of a second copy (#3319)

Milestone 333 step 5, and rule 27 — the counter had a tuning point from step
4 and no operator-facing one until now.

The task said to reuse the snippet badge's classes rather than mint a parallel
set, citing the eight duplicated CSS families the ledger already carries
(#3207). `.usage-tag` lived in SnippetListView's SCOPED block, so "reuse" was
not available: copying it into the rule pane would have been the ninth family,
and importing it is not a thing a scoped block permits. So it was promoted
rather than copied.

Three pieces, each of which existed once and now exists once:

- `components.css` gains `.usage-tag` / `.usage-dead`, geometry and colour
  only, with the scoped original deleted rather than left behind.
- `UsageBadge.vue` holds the logic the two lists would otherwise duplicate —
  the >=3 dead-weight threshold, the empty-string-renders-nothing rule, the
  tooltip.
- `types/usage.ts` holds `RecordUsage`, one client type over two tables.
  `SnippetUsage` becomes an alias, so no existing consumer changes.

THE ADVICE IS A PROP, and that is the substance rather than the plumbing. The
counts read identically for every kind; the remedy does not. A snippet offered
and never opened should probably be rewritten or deleted — one action. A rule
in the same position has TWO possible causes and the operator has to pick:
its trigger may fire on the wrong work, in which case `when_to_apply` wants
rewording, or it may genuinely not be wanted. Baking "delete it" into the
component would give the wrong nudge half the time on the surface where being
wrong is most expensive, since a deleted rule stops binding behaviour.

The route zero-fills every row through `usage_for_rules`, one aggregate per
page — per-row would be N+1 by construction. That matters more here than for
snippets: every rule on every existing install predates `rule_usage_events`,
so the zero-filled shape IS the common case for a while, and a route that
attached the key only where it found events would leave the badge reading
undefined on almost every row.

`usage_for_rules` had no test at all — step 1 covered the write path and the
zero shape and left the aggregate uncovered, which only became load-bearing
when a list started rendering it. It now has an integration test over real
Postgres, including that a rule with no events comes back zero-filled rather
than absent.

Recorded as snippet #3460, per the design system's own instruction that the
component layer lives as snippets rather than as prose.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TcCs1CcQ1ormdnzSshKqvN

tests/test_routes_rulebooks.py

@@ -122,3 +122,27 @@ def test_rule_and_subscription_handlers_callable():
         "relate_rules", "unrelate_rules",
     ):
         assert callable(getattr(rb_routes, name))
+
+
+def test_the_rule_list_zero_fills_usage_on_every_row():
+    """Milestone 333 step 5, asserted the only way this harness allows.
+
+    There is no live-HTTP fixture here (see this module's docstring), so this
+    reads the handler's source. What it can still prove is the property that
+    gets forgotten: the route must attach the key to EVERY row, zero-filled,
+    rather than only to rows that happen to have events. Every rule on every
+    existing install predates `rule_usage_events`, so a route that only
+    attached the key when it found something would leave the badge component
+    reading `undefined` on almost every row — and the difference between "no
+    events" and "no field" is exactly the distinction #2663 is about.
+    """
+    import inspect
+
+    from scribe.routes import rulebooks as rb_routes
+
+    src = inspect.getsource(rb_routes.list_rules)
+    assert "usage_for_rules" in src, "the rule list does not read usage at all"
+    assert "empty_rule_usage()" in src, (
+        "the rule list does not zero-fill — a rule with no events would come "
+        "back without the key rather than with an empty one"
+    )

tests/test_services_rule_usage.py

@@ -116,3 +116,65 @@ def test_the_model_serialises_the_fields_the_ratio_needs():
     # created_at is server-defaulted, so it is None until the row is flushed —
     # `iso()` must tolerate that rather than raising on a fresh instance.
     assert row["created_at"] is None
+
+
+# ─── the readout (milestone 333 step 5) ──────────────────────────────────────
+# Integration: a real GROUP BY over a real table. Step 1 unit-tested the WRITE
+# path and the zero shape and left the aggregate uncovered, which only became
+# load-bearing when the rule list started rendering it.
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_usage_for_rules_aggregates_per_rule(_dispose_engine):
+    from sqlalchemy import delete
+
+    from scribe.models import async_session
+    from scribe.models.rule_usage import RuleUsageEvent
+
+    async with async_session() as s:
+        s.add_all([
+            RuleUsageEvent(user_id=990020, rule_id=6001,
+                           event=SURFACED, source="write_path_rule"),
+            RuleUsageEvent(user_id=990020, rule_id=6001,
+                           event=SURFACED, source="write_path_rule"),
+            RuleUsageEvent(user_id=990020, rule_id=6001,
+                           event=PULLED, source="mcp_get_rule"),
+            RuleUsageEvent(user_id=990020, rule_id=6002,
+                           event=SURFACED, source="write_path_rule"),
+        ])
+        await s.commit()
+    try:
+        out = await rule_usage.usage_for_rules([6001, 6002, 6003])
+
+        assert out[6001]["surfaced_count"] == 2
+        assert out[6001]["pull_count"] == 1
+        assert out[6001]["last_surfaced_at"] is not None
+        assert out[6001]["last_pulled_at"] is not None
+
+        # Surfaced twice as often as it was opened — never, in this case.
+        assert out[6002]["surfaced_count"] == 1
+        assert out[6002]["pull_count"] == 0
+        assert out[6002]["last_pulled_at"] is None
+
+        # A rule with NO events still comes back, zero-filled. The caller must
+        # never have to tell "no events" from "not in the result" — and on any
+        # existing install that is nearly every rule.
+        assert out[6003] == rule_usage.empty_rule_usage()
+    finally:
+        async with async_session() as s:
+            await s.execute(
+                delete(RuleUsageEvent).where(RuleUsageEvent.user_id == 990020)
+            )
+            await s.commit()
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_usage_for_rules_on_an_empty_id_list_asks_the_database_nothing(
+    _dispose_engine,
+):
+    """The list route calls this with whatever the page holds, which on an
+    empty topic is nothing. An unguarded `IN ()` is both a pointless round trip
+    and, on some drivers, a syntax error."""
+    assert await rule_usage.usage_for_rules([]) == {}