feat: knowledge expiry / TTL and artifact versioning

[tgosoul2019]

Context

Suggested by Claude 3.7 and Gemini 2.0 during LLM evaluation. Critical for production use cases where knowledge has a shelf life.

Problem

Currently, artifacts are immutable and permanent. There's no way to:

1. Mark an artifact as superseded by a newer version
2. Set an expiry date after which it should be excluded from search
3. Query the 'current' version of a mutable knowledge item

Proposed Schema Extensions

TTL field

{
  "artifact_id": "uuid-v4",
  "expires_at": "2026-12-31T23:59:59Z",  // optional ISO 8601
  "status": "active | superseded | expired"
}

Versioning via lineage

A new version of an artifact is published with parent_id pointing to the previous version and a version_of field indicating the canonical ID:

{
  "artifact_id": "uuid-v2",
  "lineage": {
    "parent_id": "uuid-v1",
    "version_of": "uuid-v1"  // canonical ID stays stable
  }
}

API additions

# Publish new version
v2 = node.publish_version(
    artifact_id="uuid-v1",  # the artifact being replaced
    title="Rate Limiting Strategies v2",
    content="Updated content...",
)

# Get current version
current = node.get_current(canonical_id)

# Search excludes expired + superseded by default
results = node.search("rate limiting")          # active only
results = node.search("rate limiting", include_superseded=True)

Acceptance Criteria

• expires_at field in schema (SPEC.md)
• status field: active | superseded | expired
• node.publish_version(artifact_id, ...) method
• node.get_current(canonical_id) method
• Search respects TTL/status by default
• Python SDK + tests
• RFC-001 §3.1 schema update

Related

• SPEC.md §3.1 (Artifact Schema)
• Suggested by: Claude 3.7, Gemini 2.0