fix(assistant): align with #224 head - catalogue driver counts, no card badge, corpus doc 187

Author: gativarshney

docs/foomatic-assistant.md

@@ -94,7 +94,7 @@ Values live in `lib/assistant/constants.ts`; `yarn assistant:eval` fails if this
 
 ## Testing
 
-- `lib/assistant/__tests__/` — always-run fixture suites: a 156-utterance natural-language corpus (`corpus.ts`) pinning intents and parse details, entity-resolution cases, execution-state semantics (unknown-never-false, duplex, relaxations, better-dimensions), and grounding property tests over rendered responses (every card id and similarity percentage must trace to input data; banned terminology can never appear).
+- `lib/assistant/__tests__/` — always-run fixture suites: a 187-utterance natural-language corpus (`corpus.ts`) pinning intents and parse details, entity-resolution cases, execution-state semantics (unknown-never-false, duplex, relaxations, better-dimensions), and grounding property tests over rendered responses (every card id and similarity percentage must trace to input data; banned terminology can never appear).
 - `lib/assistant/__tests__/assistant-artifact.test.ts` — the same engine against the real generated artifacts (skipped automatically when they are absent, e.g. CI's pre-generate test run).
 - `tools/assistant-eval/run.ts` (`yarn assistant:eval`) — corpus accuracy, a full grounding sweep, the approved end-to-end flows, latency and artifact-size measurement, and the tunables/wording drift gates. Requires generated data, like `tools/eval/`.
 

lib/assistant/__tests__/assistant-artifact.test.ts

@@ -206,6 +206,21 @@ describe.skipIf(!present)("assistant against real foomatic artifacts", () => {
     expect(better.execution.kind).toBe("clarify")
   })
 
+  it("real recommendation cards never show a driver count", async () => {
+    // The real shards carry no driver total and the catalogue's must not be
+    // substituted in: a driver count is not a measure of support quality.
+    for (const query of ["what printers are similar to this?", "why was HP LaserJet 4P recommended"]) {
+      const turn = await runAssistant(query, lj4Context, data)
+      for (const block of turn.plan.blocks) {
+        if (block.kind !== "printer-cards") continue
+        for (const card of block.printers) {
+          if (card.score !== undefined) expect(card.driverCount).toBeUndefined()
+        }
+      }
+      expect(planText(turn.plan)).not.toMatch(/listed drivers/)
+    }
+  })
+
   it("every similarity percentage rendered anywhere matches a real shard score", async () => {
     const shard = await data.getRecommendations("HP-LaserJet_4")
     const scores = new Set(shard.map(entry => Math.round(entry.score * 100)))

lib/assistant/__tests__/fixtures.ts

@@ -64,39 +64,39 @@ export const RECOMMENDATIONS: Record<string, RecommendationEntry[]> = {
   "HP-LaserJet_4": [
     {
       id: "HP-LaserJet_4P", score: 0.895, manufacturer: "HP", model: "LaserJet 4P",
-      status: "Perfect", type: "laser", driverCount: 6,
+      status: "Perfect", type: "laser",
       sharedFeatures: ["Preferred Linux driver: hplip", "Laser printer", "PCL 5e", "Similar resolution (300-600 dpi)", "Excellent Linux driver support"],
     },
     {
       id: "HP-LaserJet_5", score: 0.885, manufacturer: "HP", model: "LaserJet 5",
-      status: "Perfect", type: "laser", driverCount: 8,
+      status: "Perfect", type: "laser",
       sharedFeatures: ["Preferred Linux driver: hplip", "Laser printer", "PCL 5e"],
     },
     {
       id: "Okidata-OL400", score: 0.61, manufacturer: "Okidata", model: "OL400",
-      status: "Mostly", type: "laser", driverCount: 2,
+      status: "Mostly", type: "laser",
       sharedFeatures: ["Laser printer"],
     },
     {
       id: "Xerox-Phaser_6100", score: 0.52, manufacturer: "Xerox", model: "Phaser 6100",
-      status: "Perfect", type: "laser", driverCount: 4,
+      status: "Perfect", type: "laser",
       sharedFeatures: ["Laser printer"],
     },
   ],
   "Canon-BJC-210": [
     {
       id: "Epson-Stylus_Color", score: 0.71, manufacturer: "Epson", model: "Stylus Color",
-      status: "Perfect", type: "inkjet", driverCount: 5,
+      status: "Perfect", type: "inkjet",
       sharedFeatures: ["Inkjet printer", "Color printing"],
     },
     {
       id: "HP-DeskJet_560C", score: 0.55, manufacturer: "HP", model: "DeskJet 560C",
-      status: "Perfect", type: "inkjet", driverCount: 6,
+      status: "Perfect", type: "inkjet",
       sharedFeatures: ["Inkjet printer", "Color printing"],
     },
     {
       id: "IBM-4019", score: 0.4, manufacturer: "IBM", model: "4019",
-      status: "Unknown", type: "laser", driverCount: 2,
+      status: "Unknown", type: "laser",
       sharedFeatures: [],
     },
   ],

lib/assistant/__tests__/respond.test.ts

@@ -68,6 +68,13 @@ describe("grounding: every rendered claim traces to fixture data", () => {
                 knownScores.has(Math.round(card.score * 100)),
                 `"${testCase.q}" rendered a similarity score not present in any shard`
               ).toBe(true)
+              // A driver total is not a support-quality signal, so it must
+              // never ride alongside a similarity score on a recommendation
+              // card (PR #224 review decision).
+              expect(
+                card.driverCount,
+                `"${testCase.q}" put a driver count on a recommendation card`
+              ).toBeUndefined()
             }
           }
         }
@@ -105,6 +112,45 @@ describe("honest language for key flows", () => {
     expect(text).toContain("not a promise")
   })
 
+  it("recommendation cards never carry a driver count, on either recommendation flow", async () => {
+    for (const query of ["what printers are similar to this?", "why was hp laserjet 4p recommended"]) {
+      const turn = await runAssistant(query, LJ4_CONTEXT, data)
+      const cards = turn.plan.blocks.filter(block => block.kind === "printer-cards")
+      expect(cards.length, `"${query}" rendered no cards to check`).toBeGreaterThan(0)
+      for (const block of cards) {
+        for (const card of block.printers) {
+          expect(card.score, `"${query}" card ${card.id} is not recommendation-backed`).toBeDefined()
+          expect(card.driverCount, `"${query}" card ${card.id} showed a driver count`).toBeUndefined()
+        }
+      }
+      expect(allText(turn.plan)).not.toMatch(/listed drivers/)
+    }
+  })
+
+  it("catalogue-backed search cards still show driver counts", async () => {
+    // The badge is dropped from recommendation cards specifically, not removed
+    // from the assistant: a directory-style result still reports the total.
+    const turn = await runAssistant("find colour laser printers", HOME_CONTEXT, data)
+    const cards = turn.plan.blocks.find(block => block.kind === "printer-cards")
+    expect(cards).toBeDefined()
+    if (cards && cards.kind === "printer-cards") {
+      expect(cards.printers.some(card => typeof card.driverCount === "number")).toBe(true)
+    }
+  })
+
+  it("only an explicit driver-options comparison reports driver totals", async () => {
+    const turn = await runAssistant("similar printers with better driver options", LJ4_CONTEXT, data)
+    const text = allText(turn.plan)
+    // Anchor total comes from the catalogue, not from the recommendation shard.
+    expect(text).toContain("list more drivers than its 6")
+    const cards = turn.plan.blocks.filter(block => block.kind === "printer-cards")
+    for (const block of cards) {
+      for (const card of block.printers) {
+        expect(card.driverCount).toBeUndefined()
+      }
+    }
+  })
+
   it("similar-printers responses state that similarity is not a compatibility promise", async () => {
     const turn = await runAssistant("what printers are similar to this?", LJ4_CONTEXT, data)
     const text = allText(turn.plan)

lib/assistant/execute.ts

@@ -478,7 +478,10 @@ async function executeSimilar(
       entry => entry.status !== "Unknown" && (STATUS_RANK[entry.status] ?? 0) > sourceRank
     )
   } else if (better === "drivers") {
-    filtered = filtered.filter(entry => entry.driverCount > (source.driverCount ?? 0))
+    // The shard carries no driver total, so the count comes from the local
+    // catalogue - the same lookup the resolution arm below uses.
+    const anchorDrivers = source.driverCount ?? 0
+    filtered = filtered.filter(entry => (byId.get(entry.id)?.driverCount ?? 0) > anchorDrivers)
   } else if (better === "resolution") {
     sourceMaxDpi = typeof source.maxDpi === "number" ? source.maxDpi : null
     if (sourceMaxDpi === null) {

lib/assistant/respond.ts

@@ -68,6 +68,11 @@ function summaryFeatures(summary: PrinterSummary): string[] {
   return features
 }
 
+// A recommendation card deliberately carries no driver count: a high driver
+// total is not a measure of good support, so it must never sit next to a
+// similarity score as though it were one (docs/foomatic-data-formats.md).
+// Driver counts belong on catalogue-backed cards (summaryCard) and in answers
+// to an explicit "better in driver options" question.
 function recommendationCard(entry: RecommendationEntry): PrinterCardData {
   const tier = confidenceTier(entry.score)
   return {
@@ -76,7 +81,6 @@ function recommendationCard(entry: RecommendationEntry): PrinterCardData {
     model: entry.model ?? entry.id,
     status: entry.status,
     type: entry.type !== "unknown" ? entry.type : undefined,
-    driverCount: entry.driverCount,
     score: entry.score,
     tierLabel: tier.label,
     tierTone: tier.tone,
@@ -248,7 +252,7 @@ export function buildResponse(execution: Execution): ResponsePlan {
       return buildComparison(execution.a, execution.b)
 
     case "explanation":
-      return buildExplanation(execution.source, execution.entry)
+      return buildExplanation(execution)
 
     case "explanation-none":
       return {
@@ -557,16 +561,16 @@ function buildComparison(a: Printer, b: Printer): ResponsePlan {
   }
 }
 
-function buildExplanation(source: PrinterSummary, entry: RecommendationEntry): ResponsePlan {
+function buildExplanation(execution: Extract<Execution, { kind: "explanation" }>): ResponsePlan {
+  const { source, entry } = execution
   const sourceName = printerName(source)
   const entryName = `${entry.manufacturer ?? ""} ${entry.model ?? entry.id}`.trim()
   const tier = confidenceTier(entry.score)
   const blocks: ResponseBlock[] = [
     text(
       `${entryName} appears in ${sourceName}'s similar-printers list with a ${similarityPercent(entry.score)} score, ` +
         `in the "${tier.label}" tier. The score is a comparison of recorded printer features - it is not a promise that ` +
-        `one printer can replace the other. ${entryName}'s own Foomatic Linux support grade is ${entry.status}, with ` +
-        `${entry.driverCount} listed drivers.`
+        `one printer can replace the other. ${entryName}'s own Foomatic Linux support grade is ${entry.status}.`
     ),
   ]
   if (entry.sharedFeatures.length > 0) {

lib/assistant/types.ts

@@ -153,7 +153,6 @@ export interface RecommendationEntry {
   model?: string
   status: string
   type: string
-  driverCount: number
 }
 
 export type Execution =