refactor(api): pull recommendation strings + reasonings into named constants

cache-readonly.types.ts now exports two const-object enums:

  THRESHOLD_RECOMMENDATIONS = { TIGHTEN, LOOSEN, OPTIMAL, INSUFFICIENT_DATA }
  TOOL_EFFECTIVENESS_RECOMMENDATIONS = { INCREASE_TTL, OPTIMAL, DECREASE_TTL_OR_DISABLE }

with the existing union types (ThresholdRecommendationKind,
ToolEffectivenessRecommendation) derived from them via
typeof[keyof typeof].

The four threshold-recommendation reasoning templates also move out
of the service, into a THRESHOLD_REASONINGS map of small functions
that take only the relevant context. The "% of foo" formatting is
now expressed once via a local formatPct helper.

CacheReadonlyService imports the consts and the reasoning map and
references them by name, so adding or renaming a recommendation no
longer requires touching the inline strings in two places.

Author: jamby77

apps/api/src/cache-proposals/cache-readonly.service.ts

@@ -7,6 +7,11 @@ import { ConnectionRegistry } from '../connections/connection-registry.service';
 import { CacheResolverService, type ResolvedCache } from './cache-resolver.service';
 import { CacheNotFoundError, InvalidCacheTypeError } from './errors';
 import { readHashInt } from '../common/utils/valkey-fields';
+import {
+  THRESHOLD_RECOMMENDATIONS,
+  THRESHOLD_REASONINGS,
+  TOOL_EFFECTIVENESS_RECOMMENDATIONS,
+} from './cache-readonly.types';
 import type {
   CacheHealth,
   CacheHealthWarning,
@@ -190,8 +195,8 @@ export class CacheReadonlyService {
         near_miss_rate: 0,
         avg_hit_similarity: 0,
         avg_miss_similarity: 0,
-        recommendation: 'insufficient_data',
-        reasoning: `Only ${sampleCount} samples collected; ${minSamples} required for a reliable recommendation.`,
+        recommendation: THRESHOLD_RECOMMENDATIONS.INSUFFICIENT_DATA,
+        reasoning: THRESHOLD_REASONINGS.insufficientData(sampleCount, minSamples),
       };
     }
     const hits = filtered.filter((s) => s.result === 'hit');
@@ -214,16 +219,16 @@ export class CacheReadonlyService {
     let recommendedThreshold: number | undefined;
     let reasoning: string;
     if (uncertainHitRate > 0.2) {
-      recommendation = 'tighten_threshold';
+      recommendation = THRESHOLD_RECOMMENDATIONS.TIGHTEN;
       recommendedThreshold = Math.max(0, threshold - config.uncertainty_band * 1.5);
-      reasoning = `${(uncertainHitRate * 100).toFixed(1)}% of hits are in the uncertainty band — tighten the threshold.`;
+      reasoning = THRESHOLD_REASONINGS.tighten(uncertainHitRate);
     } else if (nearMissRate > 0.3 && avgNearMissDelta < 0.03) {
-      recommendation = 'loosen_threshold';
+      recommendation = THRESHOLD_RECOMMENDATIONS.LOOSEN;
       recommendedThreshold = threshold + avgNearMissDelta;
-      reasoning = `${(nearMissRate * 100).toFixed(1)}% of misses are very close to the threshold — consider loosening.`;
+      reasoning = THRESHOLD_REASONINGS.loosen(nearMissRate);
     } else {
-      recommendation = 'optimal';
-      reasoning = `Hit rate ${(hitRate * 100).toFixed(1)}% with ${(uncertainHitRate * 100).toFixed(1)}% uncertain hits — threshold appears well-calibrated.`;
+      recommendation = THRESHOLD_RECOMMENDATIONS.OPTIMAL;
+      reasoning = THRESHOLD_REASONINGS.optimal(hitRate, uncertainHitRate);
     }
 
     return {
@@ -257,11 +262,14 @@ export class CacheReadonlyService {
       const policyTtl = await this.readToolPolicyTtl(client, cache.prefix, toolName);
       let recommendation: ToolEffectivenessRecommendation;
       if (hitRate > 0.8) {
-        recommendation = policyTtl !== null && policyTtl < 3600 ? 'increase_ttl' : 'optimal';
+        recommendation =
+          policyTtl !== null && policyTtl < 3600
+            ? TOOL_EFFECTIVENESS_RECOMMENDATIONS.INCREASE_TTL
+            : TOOL_EFFECTIVENESS_RECOMMENDATIONS.OPTIMAL;
       } else if (hitRate >= 0.4) {
-        recommendation = 'optimal';
+        recommendation = TOOL_EFFECTIVENESS_RECOMMENDATIONS.OPTIMAL;
       } else {
-        recommendation = 'decrease_ttl_or_disable';
+        recommendation = TOOL_EFFECTIVENESS_RECOMMENDATIONS.DECREASE_TTL_OR_DISABLE;
       }
       entries.push({
         tool: toolName,

apps/api/src/cache-proposals/cache-readonly.types.ts

@@ -41,11 +41,28 @@ export interface AgentCacheHealth extends CacheHealthCommon {
 
 export type CacheHealth = SemanticCacheHealth | AgentCacheHealth;
 
+export const THRESHOLD_RECOMMENDATIONS = {
+  TIGHTEN: 'tighten_threshold',
+  LOOSEN: 'loosen_threshold',
+  OPTIMAL: 'optimal',
+  INSUFFICIENT_DATA: 'insufficient_data',
+} as const;
+
 export type ThresholdRecommendationKind =
-  | 'tighten_threshold'
-  | 'loosen_threshold'
-  | 'optimal'
-  | 'insufficient_data';
+  (typeof THRESHOLD_RECOMMENDATIONS)[keyof typeof THRESHOLD_RECOMMENDATIONS];
+
+const formatPct = (value: number): string => `${(value * 100).toFixed(1)}%`;
+
+export const THRESHOLD_REASONINGS = {
+  insufficientData: (sampleCount: number, minSamples: number): string =>
+    `Only ${sampleCount} samples collected; ${minSamples} required for a reliable recommendation.`,
+  tighten: (uncertainHitRate: number): string =>
+    `${formatPct(uncertainHitRate)} of hits are in the uncertainty band — tighten the threshold.`,
+  loosen: (nearMissRate: number): string =>
+    `${formatPct(nearMissRate)} of misses are very close to the threshold — consider loosening.`,
+  optimal: (hitRate: number, uncertainHitRate: number): string =>
+    `Hit rate ${formatPct(hitRate)} with ${formatPct(uncertainHitRate)} uncertain hits — threshold appears well-calibrated.`,
+} as const;
 
 export interface ThresholdRecommendation {
   category: string;
@@ -61,10 +78,14 @@ export interface ThresholdRecommendation {
   reasoning: string;
 }
 
+export const TOOL_EFFECTIVENESS_RECOMMENDATIONS = {
+  INCREASE_TTL: 'increase_ttl',
+  OPTIMAL: 'optimal',
+  DECREASE_TTL_OR_DISABLE: 'decrease_ttl_or_disable',
+} as const;
+
 export type ToolEffectivenessRecommendation =
-  | 'increase_ttl'
-  | 'optimal'
-  | 'decrease_ttl_or_disable';
+  (typeof TOOL_EFFECTIVENESS_RECOMMENDATIONS)[keyof typeof TOOL_EFFECTIVENESS_RECOMMENDATIONS];
 
 export interface ToolEffectivenessEntry {
   tool: string;