Fix critical bugs, reorganize code, add comprehensive testing

[naftaly]

This PR addresses multiple bugs, improves code organization, and adds comprehensive testing and documentation to the Arsenal caching library.

Bug Fixes

• Fixed LRU eviction not working - MemoryArsenal.updateTimestamp() was mutating a struct copy without writing it back to the cache dictionary. Items were never being re-ordered by access time.
• Fixed DiskArsenal initialization race condition - Cost was calculated asynchronously in init, but operations could run before completion. Added costCalculationTask pattern with ensureCostCalculated() awaited before any cost-modifying operations (set, clear, purge).
• Replaced debug print statements with os.Logger - Each implementation now has its own categorized logger for proper production logging.

Code Organization

Reorganized Arsenal.swift into separate files by responsibility:

• Arsenal.swift - Core types (ArsenalItem, ArsenalActor, ArsenalImp, Arsenal)
• Implementations/MemoryArsenal.swift - LRU memory cache
• Implementations/DiskArsenal.swift - File-based disk cache with ArsenalURLProvider
• Implementations/SwiftDataArsenal.swift - Experimental SwiftData backend
• ImageArsenal.swift - UIImage conformance and SwiftUI environment key

Documentation

• Added comprehensive Swift DocC documentation to all public APIs
• Documented all parameters, return values, and usage examples
• Added availability annotations and warnings for experimental features

Testing

Unit Tests (17 tests):

• Basic operations (set, get, remove, URL-based keys)
• Memory cache (LRU ordering, cost tracking, purge on limit)
• Disk cache (staleness purge, cost-based purge)
• Combined cache (disk→memory promotion, dual-layer storage)
• Edge cases (nonexistent keys, overwrites, empty cache purge)

Benchmarks (12 tests):

• Memory: set, get, set with purge
• Disk: set, get
• Combined: set both layers, get with promotion
• Large items: 1MB memory/disk writes
• Throughput: mixed read/write workload
• Clear: memory and disk

CI/CD

• Added .swift-version file (6.2)
• Added GitHub Actions workflow for benchmarks (.github/workflows/benchmarks.yml)
  • Runs on PRs
  • Parses XCTest output and generates formatted markdown report
  • Posts results as PR comment

Test Plan

• All 17 unit tests pass
• All 12 benchmark tests pass
• swift build succeeds
• swiftformat passes
• LRU eviction verified working (access updates ordering)
• Disk cost calculation completes before operations proceed

[github-actions]

🚀 Arsenal Cache Performance Benchmarks

Multi-layer caching with LRU eviction and disk persistence

Test Hardware: Apple M1 (Virtual), 7 GB RAM

Memory Cache Operations

Operation	Items	Time	Per-Op	Status
Get	1000	122.0ms	122.0 μs	⚠️ OK
Set	1000	132.0ms	132.0 μs	⚠️ OK
Set (with purge)	500	270.0ms	540.0 μs	⚠️ OK

Disk Cache Operations

Operation	Items	Time	Per-Op	Status
Get	100	132.0ms	1.32 ms	✅ Excellent
Set	100	138.0ms	1.38 ms	✅ Excellent

Combined Cache (Memory + Disk)

Operation	Items	Time	Per-Op	Status
Get (disk→memory promotion)	100	142.0ms	1.42 ms	✅ Excellent
Set (both layers)	100	695.0ms	6.95 ms	✅ Good

Large Items (1 MB each)

Storage	Items	Time	Per-Item	Status
Disk	20	134ms	6.7ms	✅ Excellent
Memory	50	125ms	2.5ms	✅ Excellent

Throughput (Mixed Read/Write)

Operation	Ops	Time	Ops/sec	Status
Memory (33% write, 67% read)	5,000	137ms	36,496	⚠️ OK

Clear Operations

Storage	Items	Time	Status
Disk	100	127ms	✅ Good
Memory	1000	136ms	✅ Good

Performance Characteristics

Status Legend

• ✅ Excellent/Good: Optimal performance
• ⚠️ OK: Acceptable, monitor in production
• ❌ Review: May need optimization

Architecture

• Memory cache: LRU eviction with cost-based limits
• Disk cache: File-based with staleness and cost eviction
• Combined: Automatic disk→memory promotion on read
• Thread safety: @globalActor isolation via ArsenalActor

---

Total benchmarks: 12 passed | Generated 2025-11-30 00:06:40