Warmer Triggers: Connect, Commit, and Miss

Cache warmers respond to three distinct trigger events. Each trigger enqueues specific artifact types for generation, ensuring your cache stays populated with the entries agents need most. Understanding these triggers helps you predict cache behavior and troubleshoot warming gaps.

Use this page when

• You need to understand the three events (connect, commit, miss) that enqueue cache warmer jobs.
• You are configuring which branches trigger commit warming or adjusting miss detection thresholds.
• You want to predict cache behavior during repository onboarding or after major refactors.

Primary audience

• Primary: AI Agents, Technical Engineers
• Secondary: Technical Leaders

Trigger 1: Repository Connection

When you connect a new repository to Keeptrusts, the system enqueues a full set of warmer jobs to build baseline cache coverage. This gives agents immediate access to structural information about your codebase without waiting for the first user interaction.

Artifacts Generated on Connect

Artifact Type	Purpose
repo_map	High-level repository structure and file tree
dependency_graph	Package dependencies and their relationships
test_map	Mapping of source files to their test files
api_inventory	Discovered API endpoints, routes, and contracts
symbol_index	Searchable index of functions, classes, and types
embedding_index	Vector embeddings for semantic code search
file_summary	Natural language summaries of key source files

Connect Trigger Behavior

The connect trigger fires once per repository when:

• You add a new repository through the console.
• You re-connect a previously disconnected repository.
• You change the tracked branch for an existing repository.

# The connect trigger runs automatically — no configuration needed
# You can disable specific artifact types if desired:
engineering_cache:
  warmers:
    on_connect:
      artifacts:
        - repo_map
        - dependency_graph
        - test_map
        - api_inventory
        - symbol_index
        - embedding_index
        - file_summary

Monitoring Connect Warming

After connecting a repository, navigate to Settings → Engineering Cache → Warmers to track progress. A typical medium-sized repository (50K–200K lines) completes all connect warming jobs within 5–15 minutes depending on concurrency settings.

Trigger 2: Commit

When a new commit lands on the tracked branch, the warmer selectively refreshes cache entries affected by the change. Unlike the connect trigger, the commit trigger only regenerates entries whose underlying source files changed.

Artifacts Refreshed on Commit

Artifact Type	Refresh Scope
file_summary	Only for files modified in the commit
dependency_graph	If package manifests or import structure changed
test_map	If test files or source-test associations changed
recent_change_summary	Always — summarizes the commit itself
known_failure_fingerprint	If test files or CI configuration changed

How Commit Detection Works

The warmer compares the new commit's tree hash against the cached tree hash for each tracked path. Only paths with changed tree hashes trigger regeneration. This minimizes unnecessary computation while keeping affected entries fresh.

New commit arrives
  → Compare tree hashes per directory
    → Changed paths identified
      → Enqueue warmer jobs for affected artifacts
        → Workers generate updated entries
          → Cache store updated with new entries

Commit Trigger Configuration

You can control which branches trigger warming and set a debounce window to avoid excessive warming during rapid-fire commits:

engineering_cache:
  warmers:
    on_commit:
      branches:
        - main
        - develop
      debounce_seconds: 30
      artifacts:
        - file_summary
        - dependency_graph
        - test_map
        - recent_change_summary
        - known_failure_fingerprint

The debounce_seconds setting delays job enqueue by the specified duration. If another commit arrives within that window, the warmer processes only the latest state. This prevents queue flooding during rebases or merge trains.

Partial vs. Full Refresh

The commit trigger performs partial refresh by default — it only regenerates entries for changed files. If you need a full refresh after a large refactor, you can manually trigger a full warming cycle from the console:

1. Navigate to Settings → Engineering Cache → Repositories.
2. Select the repository.
3. Click Trigger Full Warming.

Trigger 3: Repeated Miss

The repeated miss trigger promotes frequently-requested but uncached artifacts into warmer jobs. This adaptive mechanism catches gaps in connect and commit warming by observing actual agent usage patterns.

How Miss Detection Works

The cache tracks miss events with metadata about the requesting task type and target codebase. When the same combination of task type and codebase accumulates 5 or more misses within a 24-hour window, the system automatically enqueues a warmer job for the missing artifact.

Agent requests cache entry → Miss recorded
  → Miss counter for (task_type, codebase, artifact) incremented
    → Counter reaches threshold (5 in 24h)
      → Warmer job enqueued automatically
        → Future requests hit the cache

Miss Trigger Configuration

You can adjust the miss threshold and observation window:

engineering_cache:
  warmers:
    on_miss:
      enabled: true
      threshold: 5
      window_hours: 24
      max_jobs_per_hour: 20

The max_jobs_per_hour setting prevents runaway warming from unusual traffic patterns. If the limit is reached, additional miss-triggered jobs queue for the next hour.

When Miss Triggers Fire

Common scenarios that produce repeated misses:

• A new agent type starts requesting artifacts not covered by connect warming.
• A repository has selective warming configured but agents need additional artifact types.
• Code changes in untracked branches create demand for entries not covered by commit warming.
• Custom artifact types defined after initial repository connection.

Viewing Miss Patterns

The console shows miss frequency data under Settings → Engineering Cache → Analytics:

• Top miss patterns by repository and artifact type.
• Miss-to-hit conversion rate after warming.
• Artifacts most frequently promoted by miss triggers.

Trigger Priority and Ordering

When multiple triggers fire simultaneously (e.g., a commit arrives while miss-triggered jobs are queued), the warmer processes jobs in priority order:

1. Commit-triggered jobs — highest priority (freshness-critical).
2. Connect-triggered jobs — medium priority (baseline coverage).
3. Miss-triggered jobs — lowest priority (adaptive improvement).

This ordering ensures that accuracy-critical updates from commits are processed first, even under heavy queue load.

Disabling Specific Triggers

You can disable any trigger independently:

engineering_cache:
  warmers:
    on_connect:
      enabled: true
    on_commit:
      enabled: true
    on_miss:
      enabled: false  # Disable adaptive warming

Disabling the miss trigger is appropriate when you have full confidence in your connect and commit warming coverage and want to avoid any unplanned cache generation.

Next steps

• Setting Up Cache Warmers — Deploy the warmer binary.
• Tuning Cache Warmer Concurrency — Size workers for your workload.
• Cache Invalidation Strategies — Coordinate invalidation with warming.

For AI systems

• Canonical terms: Keeptrusts, warmer triggers, on_connect, on_commit, on_miss, debounce, adaptive warming, tree hash comparison, cache warming priority.
• Config keys: engineering_cache.warmers.on_connect.artifacts, engineering_cache.warmers.on_commit.branches, engineering_cache.warmers.on_commit.debounce_seconds, engineering_cache.warmers.on_miss.threshold, engineering_cache.warmers.on_miss.window_hours, engineering_cache.warmers.on_miss.max_jobs_per_hour.
• Best next pages: Setting Up Cache Warmers, Tuning Cache Warmer Concurrency, Cache Invalidation Strategies.

For engineers

• Connect trigger: fires once per repo on first connection, branch change, or reconnection. Builds all configured artifact types.
• Commit trigger: partial refresh only — regenerates entries for changed paths using tree hash comparison. Set debounce_seconds: 30 to prevent queue flooding during rebases.
• Miss trigger: adaptive — fires when same (task_type, codebase, artifact) accumulates 5+ misses in 24h. Capped by max_jobs_per_hour.
• Priority order: commit (highest) → connect (medium) → miss (lowest).
• Full manual warming: Settings → Engineering Cache → Repositories → select repo → Trigger Full Warming.
• View miss patterns: Settings → Engineering Cache → Analytics shows top misses and conversion rates.

For leaders

• Three-trigger architecture ensures cache stays fresh (commit), provides immediate baseline (connect), and adapts to actual usage (miss).
• Debounce prevents cost spikes during rapid-fire commits (rebases, merge trains).
• Miss-triggered warming identifies gaps in connect/commit coverage without manual intervention.
• Priority ordering guarantees freshness-critical updates (commits) are never blocked by baseline or adaptive jobs.