feature(semantic-cache): add discovery marker protocol (0.2.0)

[jamby77]

Summary

Implements the semantic-cache side of a shared __betterdb:* discovery marker protocol. BetterDB Monitor (and the upcoming Cache Intelligence MCP tools) can now enumerate semantic-cache instances on any Valkey they already monitor — no customer configuration beyond constructing the library as before.

This is the first of a pair: the agent-cache counterpart ships in a separate PR.

Protocol

• __betterdb:caches — hash. Field = options.name, value = JSON metadata (type, prefix, version, protocol_version, capabilities, index/stats/config keys, default threshold, etc).
• __betterdb:heartbeat:<name> — string, TTL 60s, refreshed every 30s.
• __betterdb:protocol — string, SET NX 1. Version marker.

No sensitive data is written — only cache metadata.

What lands

• initialize() registers the instance in __betterdb:caches and starts a 30s heartbeat with a 60s TTL
• flush() and a new dispose() method stop the heartbeat and delete the heartbeat key, preserving the registry entry so Monitor retains history after the cache is gone
• Name collisions across cache types (e.g. constructing a semantic-cache where an agent-cache already holds the same name) throw SemanticCacheUsageError on initialize(). All other Valkey write failures are best-effort and increment a new semantic_cache_discovery_write_failed_total counter so operators can alert on ACL issues
• Opt out via SemanticCacheOptions.discovery = { enabled: false }. heartbeatIntervalMs and includeCategories are also exposed
• threshold_adjust is intentionally omitted from published capabilities until SemanticCache.check() re-reads the config hash at runtime — that's a separate follow-up

Bumps @betterdb/semantic-cache 0.1.0 → 0.2.0.

Test plan

• pnpm --filter @betterdb/semantic-cache test — 43 tests pass, including 13 new unit tests covering schema correctness, cross-type collision (throws), version-mismatch warn+overwrite, ACL-denied resilience, heartbeat TTL, opt-out, and registry-not-touched-on-stop
• pnpm --filter @betterdb/semantic-cache typecheck clean
• pnpm --filter @betterdb/semantic-cache build clean
• Integration tests (2 new) run in CI against valkey/valkey-bundle with the Search module: verify HGETALL __betterdb:caches is populated after initialize(), heartbeat TTL in range, dispose() clears heartbeat key, discovery: { enabled: false } writes nothing

---

Note

Medium Risk
Adds new best-effort Valkey writes and a background heartbeat tied to initialize()/flush()/dispose(), which could affect deployments with strict ACLs or unexpected keyspace policies. Core cache behavior is largely unchanged, but lifecycle/initialization paths now have more moving parts and timing concerns.

Overview
Adds a BetterDB discovery-marker protocol to @betterdb/semantic-cache (0.1.0 → 0.2.0): initialize() now registers cache metadata in __betterdb:caches, sets __betterdb:protocol, and maintains a 60s-TTL __betterdb:heartbeat:<name> refreshed on an interval (opt-out via SemanticCacheOptions.discovery).

Introduces cache.dispose() for graceful shutdown and updates flush()/initialization concurrency handling to stop/delete the heartbeat without deleting the registry entry; all discovery writes are best-effort with a new Prometheus counter semantic_cache_discovery_write_failed_total for ACL/permission failures, plus tests covering collisions, ACL-denied behavior, and heartbeat semantics.

^{Reviewed by Cursor Bugbot for commit 2d136fc. Bugbot is set up for automated code reviews on this repo. Configure here.}

[jamby77]

Code review

Found 1 issue:

1. _doInitialize widens an existing race window: the _initGeneration guard at L365 runs once, before the newly-added await this.registerDiscovery() at L367. If flush() fires during the multiple network awaits inside DiscoveryManager.register() (HGET + HSET + SET protocol + tickHeartbeat), it will bump the generation and set _initialized = false, but once registerDiscovery() resumes, L368 re-asserts _initialized = true and the heartbeat interval — scheduled from inside manager.register() before the method returned — keeps running against a cache whose index has already been dropped. Likewise for dispose() called during the same window: this.discovery is still null at the time of the dispose() call, so it no-ops, but manager.register() completes, schedules the interval, and then assigns this.discovery = manager — yielding a leaked heartbeat the caller thinks they've stopped. Consider re-checking this._initGeneration !== gen (and/or a shutdown/disposed flag) after the await registerDiscovery() resolves, and tearing the manager down if it changed — mirroring the shutdownCalled check that @betterdb/agent-cache uses around its fire-and-forget analytics init.

monitor/packages/semantic-cache/src/SemanticCache.ts

Lines 360 to 370 in 1033b74

	private async _doInitialize(): Promise<void> {
	const gen = this._initGeneration;
	return this.traced('initialize', async () => {
	const dim = await this.ensureIndexAndGetDimension();
	// If flush() ran while we were initializing, don't overwrite its state.
	if (this._initGeneration !== gen) return;
	this._dimension = dim;
	await this.registerDiscovery();
	this._initialized = true;
	});
	}

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[KIvanow]

A few things

1. Please resolve the conflicts
2. The version and changelog will need to be bumped
3. What new metadata does this PR start introducing other than flagging if the DB is used from our library or not?
4. This will need to be ported in a separate PR in the python library as well, but I can take a crack at that after we clear the first 3 questions

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

There are 2 total unresolved issues (including 1 from previous review).

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit ee0f92d. Configure here.}

[jamby77]

A few things

1. Please resolve the conflicts

Rebased

2. The version and changelog will need to be bumped

Bumped in package.json and CHANGELOG.md

3. What new metadata does this PR start introducing other than flagging if the DB is used from our library or not?

The PR adds three DB keys, all under a __betterdb:* namespace:

• __betterdb:caches is a hash where each field is a cache name and the value is a small JSON blob describing that cache. That's how Monitor will enumerate live caches without us having to ship per-tenant config.
• __betterdb:heartbeat:<name> is a short-TTL key the cache rewrites every 30 seconds. If it's there, the cache is alive; if it's gone, the process died or shut down cleanly. dispose() deletes it explicitly.
• __betterdb:protocol is just a version string so Monitor can tell when it's talking to an older library.

The JSON in the registry hash has: type (semantic_cache here, agent_cache for the agent-cache package), version, the prefix the cache uses for its own keys (so Monitor can scope SCANs correctly), protocol_version, and a capabilities array — that last one tells Monitor which control-plane operations the running version actually supports, e.g. ["threshold_adjust"].

For semantic-cache specifically, the marker also carries defaultThreshold, categoryThresholds, and uncertaintyBand so Monitor can render the active config without an RPC. If any customer treats their category names as sensitive, they can set discovery: { includeCategories: false } and those fields drop out.

Nothing else changes — the existing {name}:entry:* / {name}:embed:* / {name}:__stats keys are untouched, and the whole protocol can be turned off entirely with discovery: { enabled: false }. All writes are best-effort, so if Valkey rejects them (ACLs, OOM, whatever) check/store keep working.