refactor(semantic-cache): drop redundant B3 read-time threshold layer (#151)

PR #134's earlier B3 commit added a 5s-TTL read-time override (HGETALL on
each check()) and PR #148's commit added a 30s background refresh that
mutates defaultThreshold/categoryThresholds in-place. Both read the same
{prefix}:__config hash; running both is duplicated work and the file
even ended up with a duplicate `private readonly configKey: string`
field declaration.

Keep the 30s background-refresh approach (cleaner lifecycle, opt-out
flag, prometheus counter, no per-call overhead) and delete the B3
machinery:

- Removes private fields thresholdOverrides, thresholdOverridesCachedAt,
  thresholdOverridesRefresh and the THRESHOLD_OVERRIDES_TTL_MS constant.
- Removes private helpers resolveThreshold, getThresholdOverrides,
  refreshThresholdOverrides.
- Restores check()/checkBatch() threshold resolution to the simple
  options.threshold > categoryThresholds[category] > defaultThreshold
  chain; refreshConfig() updates those mutable fields.
- Deletes runtime-threshold-overrides.test.ts (covered the deleted helpers).
- Removes the duplicate configKey field declaration and constructor
  assignment.
- CHANGELOG: drop the read-time-overrides bullet, expand the
  periodic-refresh bullet to spell out hash field semantics and the
  synchronous-first-tick guarantee, and reword the Behavior change note.

Tests: 128/128 pass. Trade-off: propagation goes from ~5s to ~30s
worst-case, which is acceptable given the human-approval flow upstream.

Author: jamby77

packages/semantic-cache/CHANGELOG.md

@@ -11,15 +11,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **Periodic config refresh** — `SemanticCache` polls `{name}:__config` on a
   configurable interval (default 30s) and updates `defaultThreshold` and
-  `categoryThresholds` in-memory. Configure via the new `configRefresh` option;
-  opt out with `configRefresh: { enabled: false }`. New Prometheus counter
+  `categoryThresholds` in-memory. The first refresh fires synchronously on
+  `initialize()` so a freshly-started process picks up an already-applied
+  proposal without waiting for the first tick. Configure via the new
+  `configRefresh` option; opt out with `configRefresh: { enabled: false }`.
+  Hash field semantics: `threshold` → `defaultThreshold`,
+  `threshold:{category}` → `categoryThresholds[category]`; out-of-range values
+  (`< 0`, `> 2`, NaN) are ignored. New Prometheus counter
   `{prefix}_config_refresh_failed_total`.
-- **Runtime threshold overrides** — `check()` and `checkBatch()` also read
-  `{prefix}:__config` on each call (cached for 5s in-process) and honor
-  `threshold` / `threshold:{category}` fields. Resolution order:
-  `options.threshold` > runtime override > `categoryThresholds` > `defaultThreshold`.
-  Read failures fall back silently to constructor values; out-of-range values
-  (`< 0`, `> 2`, NaN) are dropped.
 - **`refreshConfig()`** — public method returning `boolean` for manual refresh.
 - **`threshold_adjust` capability** — added to the discovery marker's
   `capabilities` array. Monitor's apply dispatcher gates on this before writing
@@ -33,8 +32,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Behavior change
 
-- A `{prefix}:__config` Valkey hash that previously had no effect now influences
-  `check()` thresholds. Audit existing keys before upgrading.
+- A `{prefix}:__config` Valkey hash that previously had no effect now drives
+  `defaultThreshold` and `categoryThresholds` at runtime. Audit existing keys
+  before upgrading, or set `configRefresh: { enabled: false }` to keep the
+  constructor values authoritative.
 
 ## [0.3.0] - 2026-04-27
 

packages/semantic-cache/src/SemanticCache.ts

@@ -40,7 +40,6 @@ import {
 } from './discovery';
 
 const INVALIDATE_BATCH_SIZE = 1000;
-const THRESHOLD_OVERRIDES_TTL_MS = 5_000;
 
 const PACKAGE_VERSION = (require('../package.json') as { version: string }).version;
 
@@ -67,7 +66,6 @@ export class SemanticCache {
   private readonly embeddingCacheTtl: number;
   private readonly embedKeyPrefix: string;
   private readonly discoveryOptions: DiscoveryOptions;
-  private readonly configKey: string;
   private readonly _initialDefaultThreshold: number;
   private readonly _initialCategoryThresholds: Record<string, number>;
   private readonly configRefreshOptions: Required<ConfigRefreshOptions>;
@@ -80,10 +78,6 @@ export class SemanticCache {
   private _initPromise: Promise<void> | null = null;
   private _initGeneration = 0;
 
-  private thresholdOverrides: { global?: number; byCategory: Record<string, number> } | null = null;
-  private thresholdOverridesCachedAt = 0;
-  private thresholdOverridesRefresh: Promise<void> | null = null;
-
   private readonly analyticsOpts: SemanticCacheOptions['analytics'];
   private readonly usesDefaultCostTable: boolean;
   private analytics: Analytics = NOOP_ANALYTICS;
@@ -143,9 +137,6 @@ export class SemanticCache {
     this._initialDefaultThreshold = this.defaultThreshold;
     this._initialCategoryThresholds = { ...this.categoryThresholds };
 
-    // Config-hash key matches the discovery marker's config_key field
-    this.configKey = `${this.name}:__config`;
-
     // Refresh options
     const refresh = options.configRefresh ?? {};
     this.configRefreshOptions = {
@@ -254,8 +245,11 @@ export class SemanticCache {
 
     return this.traced('check', async (span) => {
       const category = options?.category ?? '';
-      const overrides = await this.getThresholdOverrides();
-      const threshold = this.resolveThreshold(category, options?.threshold, overrides);
+      const threshold =
+        options?.threshold ??
+        (category && this.categoryThresholds[category] !== undefined
+          ? this.categoryThresholds[category]
+          : this.defaultThreshold);
 
       // Resolve text and binary refs from prompt
       const { text: promptText, binaryRefs } = await this.resolvePrompt(prompt);
@@ -626,8 +620,11 @@ export class SemanticCache {
       const embeddings = await Promise.all(resolved.map(({ text }) => this.embed(text)));
 
       const category = options?.category ?? '';
-      const overrides = await this.getThresholdOverrides();
-      const threshold = this.resolveThreshold(category, options?.threshold, overrides);
+      const threshold =
+        options?.threshold ??
+        (category && this.categoryThresholds[category] !== undefined
+          ? this.categoryThresholds[category]
+          : this.defaultThreshold);
       const k = options?.k ?? 1;
       const userFilter = options?.filter;
 
@@ -1412,85 +1409,6 @@ export class SemanticCache {
     );
   }
 
-  // -- Runtime threshold overrides --
-  //
-  // Reads { prefix }:__config to honor approved cache-intelligence threshold_adjust
-  // proposals at runtime. See docs/plans/specs/spec-semantic-cache-runtime-threshold-reads.md.
-
-  private resolveThreshold(
-    category: string,
-    optionsThreshold: number | undefined,
-    overrides: { global?: number; byCategory: Record<string, number> },
-  ): number {
-    if (optionsThreshold !== undefined) {
-      return optionsThreshold;
-    }
-    if (category && overrides.byCategory[category] !== undefined) {
-      return overrides.byCategory[category];
-    }
-    if (overrides.global !== undefined) {
-      return overrides.global;
-    }
-    if (category && this.categoryThresholds[category] !== undefined) {
-      return this.categoryThresholds[category];
-    }
-    return this.defaultThreshold;
-  }
-
-  private async getThresholdOverrides(): Promise<{
-    global?: number;
-    byCategory: Record<string, number>;
-  }> {
-    const fresh =
-      this.thresholdOverrides !== null &&
-      Date.now() - this.thresholdOverridesCachedAt < THRESHOLD_OVERRIDES_TTL_MS;
-    if (fresh) {
-      return this.thresholdOverrides!;
-    }
-    if (!this.thresholdOverridesRefresh) {
-      this.thresholdOverridesRefresh = this.refreshThresholdOverrides().finally(() => {
-        this.thresholdOverridesRefresh = null;
-      });
-    }
-    await this.thresholdOverridesRefresh;
-    return this.thresholdOverrides ?? { byCategory: {} };
-  }
-
-  private async refreshThresholdOverrides(): Promise<void> {
-    let hash: Record<string, string>;
-    try {
-      hash = await this.client.hgetall(this.configKey);
-    } catch (err: unknown) {
-      // Fail open: keep prior cache (if any) and let resolution fall back to
-      // constructor categoryThresholds. Logged so operators can spot a degraded
-      // Valkey config-hash read without breaking the user-facing check() path.
-      console.warn(
-        `[semantic-cache:${this.name}] failed to read ${this.configKey}: ${errMsg(err)}`,
-      );
-      return;
-    }
-
-    const next: { global?: number; byCategory: Record<string, number> } = { byCategory: {} };
-    for (const [field, value] of Object.entries(hash)) {
-      const parsed = parseFloat(value);
-      if (!Number.isFinite(parsed) || parsed < 0 || parsed > 2) {
-        console.warn(
-          `[semantic-cache:${this.name}] config-hash override out of range: ${field}=${value}`,
-        );
-        continue;
-      }
-      if (field === 'threshold') {
-        next.global = parsed;
-      } else if (field.startsWith('threshold:')) {
-        const cat = field.slice('threshold:'.length);
-        if (cat) {
-          next.byCategory[cat] = parsed;
-        }
-      }
-    }
-    this.thresholdOverrides = next;
-    this.thresholdOverridesCachedAt = Date.now();
-  }
 
   private parseDimensionFromInfo(info: unknown[]): number {
     for (let i = 0; i < info.length - 1; i += 2) {