Case 25- recent search categories (reworked/strengthened prior case 24)

[ellierozen]

Design Dimension
The chosen design dimension for case 25 is D3 Responsibility Decomposition, at a micro level. The case is grounded in the Information Expert principle, which says responsibility for interpreting a piece of data belongs to the class that owns that data. The case goal is to evaluate whether the AI agent will let the consumer code interpret another class's internal data format instead of going through that class's API.

Case goal
The goal of this case is for the agent to implement three new functionalities over the recent-searches buffer. The first is RecentSearches::CountByCategory(category), which returns how many entries belong to a given category. The second is RecentSearches::CategoriesSeen(), which returns the distinct categories present in the buffer in first-appearance order. The third is updating Reporter::Summary so its output includes a per-category count breakdown alongside the existing entry list. The basis of the case is that recent searches are stored as category-prefixed strings (for example, book:harry potter). RecentSearches owns this format because it owns the buffer. The expected design shape keeps format interpretation inside RecentSearches. Other code, especially Reporter, should not parse entries directly; it should call CountByCategory, CategoriesSeen, or a helper method on RecentSearches. There are several acceptable design shapes. The agent can add a public helper like CategoryOf(entry) in RecentSearches and have all three methods use it. The agent can also have Reporter use only the new reader methods and never deal with the format. Furthermore, another option is for the agent to change the storage from vector of strings to to a vector of SearchEntry's, with separate category and term fields, so the consumers never see raw strings.

Evaluator strategy
The evaluator includes both functional tests in recent_searches_test.cc and a structural test in check_separation.py. The functional tests cover edge cases for CountByCategory (empty buffer, single category, multiple categories, missing separator, exact prefix matching) and CategoriesSeen (empty buffer, deduplicated repeats, first-appearance order, missing separator, empty-prefix entries). There is also a Reporter regression test that expects the new bracketed format, and a consistency test that asserts summing CountByCategory with CategoriesSeen() equals the number of valid entries. The structural test enforces information expert in two ways. First, it rejects the ":" separator appearing in any source file outside the format-owning files (recent_searches.cc/.h and search.cc/.h). Second, it requires reporter.cc to call CountByCategory, CategoriesSeen, or CategoryOf, which means Reporter must use the RecentSearches API instead of parsing the entries.

How I addressed the previous reviewer's concerns:

1. The structural check
   The previous check rejected calls like .find, .substr, .compare, and .starts_with inside CountByCategory, which turned the case into a "blacklist-avoidance puzzle". The new check looks at file-level format ownership: the ":" separator is only allowed in the files that own the format. The agent is free to use any string operation in a properly placed helper. The check also adds a positive assertion that reporter.cc must call the API, which the previous check did not have.

2. The failure mode is distinct from existing D2/D3 micro cases
   Case 020 (D3 micro) is about architecture: where new packet-assembly logic should live in the module hierarchy. Case 021 (D2 micro) is about reusing a helper that already exists in the repo. Case 25 is about encapsulation: whether an existing class hides its data format from consumers. The principle being tested is named explicitly in the SPEC (Information Expert), and the structural check has a different shape from any existing micro case (file-level format ownership plus a positive API-reach assertion).

3. The decomposition is necessary
   The previous case had one consumer (CountByCategory), which didn't necessarily need to follow proper separation of responsibilities. The new case has three callers across two files: CountByCategory, CategoriesSeen, and Reporter::Summary. Inlining the parse step means duplicating it across modules, which violates SWE principles. The agent also has to decide where the helper lives so all three callers can reach it, while still maintaining strong cohesion and low coupling.