Knowctl Versioning Analysis - Handling library API version mismatches

knowctl-versioning-analysis.md

Knowctl Versioning: Analysis and Recommendations

The Problem

When using knowctl to get documentation for libraries like ironrdp, the docs may describe an API that doesn't match the version the user is actually using. In this case:

• The knowctl topic likely had docs for ironrdp 0.5.x
• The latest version is 0.14.0 (a major API rewrite)
• Code written based on knowctl docs failed to compile with current crate versions

This is a general problem: library APIs change, but knowctl topics are static snapshots.

Root Causes

1. No version awareness: Topics don't track which version they document
2. No expiration/freshness signals: No indication of how old the docs are
3. No integration with package managers: Can't cross-reference Cargo.toml, package.json, etc.

Potential Solutions

1. Version Pinning in Topic Metadata

Add a version field to topic configuration:

topic: ironrdp
version: "0.14.0"
source_date: "2025-01-15"
docs:
  - ...

Benefits:

• Agents can warn when docs might be outdated
• Clear signal about what version is documented
• Can trigger re-fetching when version differs significantly

Drawbacks:

• Requires manual maintenance
• Semver interpretation is complex (patch vs minor vs major)

2. Version Ranges

Support multiple versions with migration guides:

topic: ironrdp
versions:
  - range: ">=0.14.0"
    docs: [...]
  - range: ">=0.5.0 <0.14.0"
    docs: [...]
    migration_to_0.14: "migration-guide.md"

Benefits:

• Explicit support for version transitions
• Migration paths for breaking changes

Drawbacks:

• High maintenance burden
• Topic size grows significantly

3. Freshness Indicators

Add metadata about documentation freshness:

topic: ironrdp
last_verified: "2025-01-01"
freshness: stale  # fresh | stale | deprecated
api_stability: unstable  # stable | unstable | experimental

An agent can then:

• Warn: "These docs are from January 2025 and the library is marked unstable"
• Suggest: "Consider using web search for the latest API"

4. Automatic Version Detection

When an agent uses knowctl for a Rust crate:

1. Check if Cargo.toml exists in the project
2. Parse the dependency version for that crate
3. Compare with topic's documented version
4. Warn or adjust behavior accordingly

Implementation:

# In knowctl
def check_version_match(topic: str, project_dir: Path) -> VersionMatch:
    topic_version = load_topic_version(topic)
    if cargo_toml := find_cargo_toml(project_dir):
        project_version = parse_dependency_version(cargo_toml, topic)
        if not semver_compatible(topic_version, project_version):
            return VersionMatch.MISMATCH
    return VersionMatch.OK

5. Hybrid Approach (Recommended)

Combine several strategies:

1. Required metadata: Every topic must have:

   • version: What version the docs cover
   • last_updated: When docs were last refreshed
   • source_url: Where to find canonical docs

2. Freshness check command:

   knowctl check-freshness ironrdp
   # Output: ironrdp docs are for v0.5.0, latest is v0.14.0 (stale)
   

3. Agent guidance in docs: Add a standard header to all topic docs:

   <!-- knowctl: version=0.5.0, check-latest-at=https://docs.rs/ironrdp -->

4. Warning system: When topic is accessed, check if:

   • Docs are older than 6 months
   • Major version mismatch detected
   • Topic marked as "unstable API"

Implementation Priority

Phase 1: Version Metadata (Low effort, high value)

• Add version and last_updated to topic schema
• Update existing topics with version info
• Add knowctl show-topic-info <topic> command

Phase 2: Freshness Warnings (Medium effort, high value)

• Add knowctl check-freshness <topic> command
• Optionally query crates.io/npm for latest versions
• Return structured data agents can act on

Phase 3: Project Integration (High effort, medium value)

• Auto-detect project dependencies
• Cross-reference with topic versions
• Surface warnings proactively

Specific Recommendations for ironrdp

Given the current situation:

1. Update the ironrdp topic to reflect 0.14.0 API
2. Add version metadata to the topic
3. Consider removing unstable topics - if a library has frequent breaking changes, maybe don't include it in knowctl (prefer web search for latest docs)
4. Mark experimental libraries - add stability: experimental flag

Alternative: Don't Document Unstable Libraries

For libraries like ironrdp that:

• Are pre-1.0 with frequent breaking changes
• Have rapidly evolving APIs
• Have good official documentation

It may be better to:

1. Remove them from knowctl entirely
2. Add a "pointer" topic that just says "use docs.rs/ironrdp for latest"
3. Let agents use scrapectl or searchctl for current docs

This acknowledges that some libraries are too unstable for static documentation snapshots.

Conclusion

The core issue is that knowctl topics are static snapshots in a dynamic ecosystem. The recommended fix is:

1. Add version metadata to all topics
2. Build freshness checking into knowctl
3. Give agents tools to detect version mismatches
4. Consider excluding highly unstable pre-1.0 libraries

For the ironrdp case specifically: either update the topic to 0.14.0 or remove it entirely and direct agents to use docs.rs/ironrdp directly via scrapectl.