cache conflicts

[cmungall]

we're seeing a lot of these, an agent needs to take this on:

• term cache files should be free of spurious diffs linkml/linkml-term-validator#9

[github-actions]

Summary: Cache Conflicts Due to Timestamp Regeneration

This issue tracks cache file conflicts caused by non-incremental timestamp updates in the ontology term validation system.

The Problem

When adding or updating disorder files, all cached ontology terms get their timestamps regenerated, not just newly added terms. This creates:

• Massive diffs: Adding 1-2 new terms causes 300-600+ line changes in cache files
• Code review friction: Reviewers cannot easily identify genuinely new terms
• Merge conflicts: Higher likelihood of cache conflicts in concurrent PRs
• Git history pollution: Difficult to track when specific terms were first introduced

Example Impact

From issue #40, adding Frontotemporal Dementia caused:

• cache/hp/terms.csv: 646 lines changed (324 additions, 322 deletions)
• cache/mondo/terms.csv: 129 lines changed (65 additions, 64 deletions)

But only 1-2 new terms were actually added. The bulk of changes are timestamp updates:

-HP:0040282,Frequent,2025-12-16T10:24:02.844891
+HP:0040282,Frequent,2025-12-23T11:16:01.374193

Root Cause

The issue originates in linkml-term-validator (upstream issue #9):

The cache implementation in src/linkml_term_validator/plugins/base.py:

1. _load_cache() reads only curie-label mappings, discarding timestamps
2. _save_to_cache() rewrites the entire file with fresh datetime.now() timestamps
3. Result: every validation run updates timestamps for all cached terms

Proposed Solutions

From the upstream issue, three main approaches:

1. Preserve original timestamps (recommended): Modify cache read/write to maintain retrieved_at for existing entries, only generating new timestamps for truly new terms
2. Append-only mode: Add new terms without rewriting the entire cache
3. Separate metadata files: Split timestamps from the core label cache

Related Issues

• Large cache diffs due to non-incremental timestamp updates #40: "Large cache diffs due to non-incremental timestamp updates" (same problem, opened Dec 2025, assigned to @dragon-ai-agent)
• Upstream: linkml/linkml-term-validator#9 (opened Jan 2026, no assignee yet)

Current Status

• The upstream issue in linkml-term-validator has been identified but remains unassigned with no active development
• Issue Large cache diffs due to non-incremental timestamp updates #40 in this repo is open and assigned to @dragon-ai-agent
• This is a duplicate tracking issue

Recommended Action

Since #40 already tracks this problem with more detail and has an assignee, I recommend:

1. Close cache conflicts #337 as duplicate of Large cache diffs due to non-incremental timestamp updates #40
2. Focus effort on the upstream fix in linkml-term-validator
3. Consider contributing the fix upstream (Option 1 requires minimal code changes)

Technical Details for Fix

The fix needs to be implemented in linkml-term-validator by modifying the cache handling:

# In _load_cache(): preserve timestamps
def _load_cache(self) -> Dict[str, Tuple[str, datetime]]:
    # Load both label AND timestamp
    return {curie: (label, retrieved_at) for ...}

# In _save_to_cache(): reuse existing timestamps
def _save_to_cache(self):
    existing_cache = self._load_cache()
    for curie, label in terms.items():
        timestamp = existing_cache[curie][1] if curie in existing_cache else datetime.now()
        # Write with preserved or new timestamp

---

Note: This summary is based on analysis of related issues and the upstream linkml-term-validator issue. No papers were cited as this is a technical infrastructure issue.