feat(semantic-cache): runtime-configurable defaultTtl via __config hash

[amitkojha05]

Closes #147.

What this does

Adds runtime TTL configuration to @betterdb/semantic-cache (TS + Python) via the existing {name}:__config hash — same mechanism as threshold_adjust. A running process picks up TTL changes on the next refreshConfig() tick without a restart.

Changes

SemanticCache (TS)

• defaultTtl is now mutable; _initialDefaultTtl captures the constructor value as the permanent fallback
• refreshConfig() reads the ttl field at the end of every tick — after threshold processing, no field collision
• Validation: positive integer seconds only. Non-finite, non-integer, zero, negative → silently ignored, current value kept. Absent field → _initialDefaultTtl restored. No throws anywhere in the path.

Discovery (TS)

• buildSemanticMetadata() in discovery.ts now advertises 'ttl_adjust' alongside 'threshold_adjust'

MCP

• New cache_propose_ttl_adjust tool registered after cache_propose_threshold_adjust
• Takes:
  • cache_name
  • new_ttl_seconds (1–604800)
  • reasoning (≥20 chars)

Example

• packages/semantic-cache/examples/monitor-proposals/index.ts extended with a TTL proposal demo loop:
  • set → verify → remove → verify fallback

Python mirrors

• _initial_default_ttl captured in __init__
• TTL block added at end of refresh_config() with identical validation logic:
  • math.isfinite
  • integer check
  • silent ignore behavior
• build_semantic_metadata() in discovery.py advertises 'ttl_adjust'

Tests

8 cases each in TS + Python — field read, fallback, restore on removal, invalid values (0, negative, float, string), timer propagation, discovery capability

What's not in this PR

The library side is fully wired — refreshConfig() reads the ttl field, validation matches the threshold pattern, and the MCP tool is registered.

The remaining pieces to close the propose→approve→apply→pickup loop live in proprietary/:

1. CacheApplyDispatcher — route proposal_type: 'ttl_adjust' to a new applySemanticTtlAdjust handler:

case 'ttl_adjust':
  await client.hset(`${cache.prefix}:__config`, 'ttl', String(payload.new_ttl_seconds));
  return { status: 'applied' };

2. MCP controller — register the semantic-ttl-adjust POST route that the cache_propose_ttl_adjust tool calls.

Both are one-line additions mirroring the existing threshold_adjust counterparts. Happy to implement if you'd prefer, or these can land internally.

---

Note

Medium Risk
Medium risk because it changes cache expiration behavior at runtime in both TS and Python, which can affect memory usage and cache hit patterns; validation is defensive and covered by new tests.

Overview
Adds a runtime-configurable semantic-cache default TTL via the existing {name}:__config hash in both @betterdb/semantic-cache (TS) and betterdb-semantic-cache (Python), with refreshConfig()/refresh_config() applying a validated positive-integer ttl value and restoring the constructor TTL when the field is removed.

Updates discovery metadata to advertise the new ttl_adjust capability, adds an MCP tool cache_propose_ttl_adjust to create TTL-change proposals, and extends the monitor-proposals example plus TS/Python test suites to cover TTL read/fallback/restore/invalid-value and refresh-tick propagation cases.

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

[cursor]

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

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

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

[amitkojha05]

@jamby77 @KIvanow Please review this PR ,would love to hear your feedback.