Fabric Artifact Freshness and Staleness

Every cached artifact in the Codebase Context Fabric has a freshness boundary. The cache must determine whether a stored artifact still reflects the current state of your code, configuration, and tooling. When something changes, affected artifacts become stale and must be regenerated. When nothing relevant changes, artifacts remain fresh and serve instantly from the cache.

Use this page when

• You need to understand how the cache determines whether a fabric artifact is still valid (fresh) or needs regeneration (stale).
• You are troubleshooting stale cache results or unexpected regeneration behavior.
• You want to configure freshness modes (strict vs. relaxed), TTL overrides, or force-refresh for specific scopes.

Primary audience

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

Freshness dimensions

The cache evaluates artifact freshness across multiple dimensions. Each dimension contributes to the overall validity of a cached artifact:

Repository ID

Each artifact is scoped to a specific repository. Artifacts from one repository never satisfy cache lookups for another, even if file names or content happen to match.

Branch and ref

Artifacts are generated for specific branch references. A repo_map artifact generated for main is distinct from one generated for feature/auth-refactor. When you switch branches, the cache serves artifacts for your current branch.

Commit SHA

The commit SHA anchors an artifact to a specific point in history. When new commits land on a branch, artifacts tied to the old SHA are candidates for staleness evaluation.

Tree hash

The git tree hash captures the state of the entire directory structure at a commit. Two commits with identical tree hashes (e.g., a merge that produces the same tree) share cached artifacts because the source state is identical.

Relevant file digests

Not every file change invalidates every artifact. Each artifact tracks which specific files it depends on. A file_summary for src/auth/session.ts only becomes stale when that specific file's content digest changes. Changes to unrelated files do not affect it.

Agent version

The AI agent version that generated an artifact affects its validity. When you upgrade to a newer agent version that produces higher-quality analysis, older artifacts are regenerated to reflect improved capabilities.

Policy and configuration digest

Your organization's policies and cache configuration affect how artifacts are generated. If you change policy rules that affect artifact generation, dependent artifacts are invalidated.

Entitlement digest

Your organization's entitlement level determines which artifact types and quality tiers are available. Changes to entitlements may require artifact regeneration at the new quality tier.

How freshness evaluation works

When your AI requests a cached artifact, the cache evaluates freshness:

1. Check repository and branch — is this artifact for the right repo and branch?
2. Compare commit/tree state — has the branch advanced since the artifact was generated?
3. Evaluate file digests — have the specific files this artifact depends on changed?
4. Verify agent version — was this artifact generated by the current agent version?
5. Check config digest — has the relevant configuration changed?

If all checks pass, the artifact is fresh and serves immediately. If any check fails, the artifact is stale.

Stale misses explained

A stale miss occurs when the cache contains an artifact that no longer reflects current state. Stale misses trigger regeneration:

• Full regeneration — the artifact is regenerated from scratch using current source state
• Incremental update — for some artifact types, only the changed portions are recomputed

Stale misses are more expensive than cache hits but cheaper than cold misses (no artifact exists at all), because the cache can sometimes use the stale artifact as a starting point for incremental regeneration.

Partial freshness and slice reuse

Not all dimensions change simultaneously. When code changes but configuration stays the same, artifacts that depend only on configuration remain fresh. The cache exploits this by tracking dependencies at a granular level.

Consider a dependency_graph artifact for a module. If you add a new file to a different module:

• The tree hash changes (new file exists)
• The commit SHA changes (new commit)
• But the specific file digests the dependency graph depends on have not changed
• The artifact remains fresh because its relevant inputs are unchanged

This granular tracking maximizes cache reuse even when the repository changes frequently.

Freshness for different artifact types

Different artifact types have different freshness profiles:

Artifact Type	Primary Freshness Signals	Typical Freshness Duration
repo_map	Tree hash, directory structure	Until any file is added/removed/moved
file_summary	Specific file digest	Until that file's content changes
dependency_graph	Import statement digests	Until imports change in tracked files
recent_change_summary	Commit range	Rolling window (e.g., 7 days)
known_failure_fingerprint	Error pattern relevance	Until root cause is fixed
tool_result	Input file digests + tool version	Until inputs or tool version change
agent_intermediate	Source digests + agent version	Until analyzed code or agent changes

Unchanged fabric slices

When a large artifact is partially stale, the cache identifies which slices remain valid. A repo_map covering 200 files might have only 5 files that changed. The cache reuses the 195 unchanged file entries and regenerates only the 5 changed ones.

This slice-level freshness means:

• Regeneration is proportional to the amount of change, not the size of the artifact
• Your AI gets updated artifacts quickly even for large codebases
• Token cost for regeneration stays low

Configuring freshness behavior

You control freshness evaluation through cache configuration:

• Strict mode — any change to tracked dimensions invalidates the artifact
• Relaxed mode — only changes to primary file digests trigger invalidation
• TTL overrides — set maximum artifact lifetime regardless of freshness signals
• Force refresh — manually invalidate all artifacts for a scope

Monitoring freshness metrics

The cache exposes freshness metrics for your organization:

• Hit rate — percentage of requests served from fresh cache
• Stale miss rate — percentage of requests that found stale artifacts
• Cold miss rate — percentage of requests with no cached artifact
• Regeneration latency — time to regenerate stale artifacts

These metrics help you understand cache effectiveness and tune freshness configuration.

For AI systems

• Canonical terms: Keeptrusts, Codebase Context Fabric, artifact freshness, staleness, commit SHA, tree hash, file digest, agent version, policy digest, entitlement digest, stale miss, partial freshness, slice reuse.
• Feature/config names: freshness dimensions (repository ID, branch/ref, commit SHA, tree hash, file digests, agent version, policy/config digest, entitlement digest), freshness modes (strict, relaxed), TTL overrides, force refresh, hit rate, stale miss rate, cold miss rate, regeneration latency.
• Best next pages: Fabric Slices Reduce Prompts, Deterministic Tool Results, Fabric Provenance.

For engineers

• Each artifact tracks which specific files it depends on via content digests. Changes to unrelated files do NOT invalidate it.
• Freshness evaluation order: repository/branch → commit/tree state → file digests → agent version → config digest.
• Stale misses trigger regeneration; they are cheaper than cold misses because the cache may use the stale artifact as a starting point for incremental update.
• Configure strict mode for security-sensitive contexts, relaxed mode for general development where only primary file digest changes matter.

For leaders

• Granular freshness tracking maximizes cache reuse: 95%+ of artifacts remain fresh during typical development because most files don’t change simultaneously.
• Stale miss cost is proportional to the amount of change, not the size of the artifact — keeps regeneration costs predictable.
• Freshness metrics (hit rate, stale miss rate, cold miss rate) are key indicators of cache health and should be monitored weekly.
• Agent version-based invalidation ensures AI improvements are reflected in cached artifacts without manual intervention.

Next steps

• Learn how fabric slices reduce prompt size using fresh cached data
• Explore how deterministic tool results use input digests for freshness
• Understand how fabric provenance records the freshness state at generation time