feat(maintenance): Distributed Maintenance Coordination via Raft (v2.0.0)

[Copilot]

In a multi-node cluster, every node independently fires the same maintenance schedules, causing compaction storms and duplicate work. This PR introduces a pluggable distributed lock that the orchestrator acquires before each scheduled job, ensuring only one node executes per schedule per cron tick.

Description

IDistributedLock interface + InProcessDistributedLock (include/maintenance/i_distributed_lock.h)

• New pluggable interface: tryAcquire(key, ttl_ms), release(key), getHolderNodeId(key), nodeId()
• InProcessDistributedLock: thread-safe in-process implementation for single-node and tests; TTL expiry checked per acquire
• Production wiring: inject a Raft-backed implementation via setDistributedLock()

Orchestrator lock integration (database_maintenance_orchestrator.*)

• setDistributedLock(shared_ptr<IDistributedLock>) — DI setter, thread-safe, nullable (disables feature)
• In executeSchedule(), lock is acquired before the window check; on failure: job → SKIPPED, DEBUG log: "schedule {id} skipped — lock held by peer {node_id}"
• RAII DistLockGuard ensures release on every exit path (success, window skip, DAG error, cancellation)

TTL computation

// lock_ttl_ms == 0 → auto-derive from window + 30 s safety margin
int64_t ttl_ms = entry.lock_ttl_ms > 0
    ? entry.lock_ttl_ms
    : window_hours * 3600'000LL + 30'000LL;

MaintenanceScheduleEntry::lock_ttl_ms (default 0) makes TTL configurable per schedule.

New fields

• MaintenanceScheduleEntry::lock_ttl_ms — serialized in toJson()/fromJson()/applyPatch()

Linked Issues

Closes #252

Type of Change

• Bug fix (non-breaking)
• New feature (non-breaking)
• Refactoring (non-breaking)
• Documentation
• Breaking change (requires MAJOR version bump — see VERSIONING.md)
• Security fix
• Other:

Breaking Change Checklist

• MAJOR version bump planned in VERSION and CMakeLists.txt
• Migration guide added in docs/migration/
• Announcement prepared for GitHub Discussions (≥ 2 weeks before release)
• CHANGELOG ### Removed / ### Changed section updated

Testing

• Unit tests added/updated
• Integration tests added/updated
• Manual testing performed
• Benchmarks run (if performance-sensitive change)

14 new tests in test_database_maintenance_orchestrator.cpp:

• DL-1: no lock configured → backwards-compatible, job runs normally
• DL-2: lock acquired → job executes, acquire + release called once
• DL-3: lock held by peer → SKIPPED, error message contains peer node ID
• DL-4/5: TTL auto-compute from window vs. explicit lock_ttl_ms
• DL-6/7: lock_ttl_ms JSON round-trip and applyPatch
• DL-8: setDistributedLock(nullptr) clears lock, no acquire/release calls
• InProcessDistributedLock: first acquires, second blocked; release; TTL expiry; getHolderNodeId after expiry

📚 Research & Knowledge (wenn applicable)

• Diese PR basiert auf wissenschaftlichen Paper(s) oder Best Practices?
  • Falls JA: Research-Dateien in /docs/research/ angelegt?
  • Falls JA: Im Modul-README unter "Wissenschaftliche Grundlagen" verlinkt?
  • Falls JA: In /docs/research/implementation_influence/ eingetragen?

Relevante Quellen:

• Paper:
• Best Practice:
• Architecture Decision:

Checklist

• Code follows project style guidelines (clang-format / clang-tidy)
• Self-review completed
• Documentation updated (if needed)
• CHANGELOG.md updated under [Unreleased]
• No new warnings introduced
• Security-sensitive paths reviewed by security maintainer (if applicable)