clavitor/issues/AUDIT-REPORT-clavis-telemetry.md

Cardinal Rule Violations Audit Report — clavis-telemetry

Auditor: Yurii (Code & Principle Review)
Domain: clavis-telemetry
Domain Owner: Hans (operations, monitoring, NOC)
Date: 2026-04-08
Handbook Version: 1.0

---

Audit Summary

4 Cardinal Rule violations identified in clavis/clavis-telemetry/:

Issue	File	Violation	Severity	Assignee
#001	main.go	Missing unique error codes	Medium	@hans
#002	main.go	Unhandled database errors	High	@hans
#003	kuma.go	Silent failure in Kuma push	High	@hans
#004	main.go	Unchecked flush error	Low	@hans

---

Cardinal Rules Status

Rule	Status	Notes
#1 — Security failures are LOUD	⚠️ Partial	Error handling present but lacks unique codes
#2 — Server never holds L2/L3	✅ Pass	Telemetry doesn't handle key material
#3 — Browser is trust anchor	N/A	Not applicable to telemetry service
#4 — Threat defenses	✅ Pass	mTLS properly implemented
#5 — WL3 GDPR-out-of-scope	✅ Pass	No PII in telemetry schema
#6 — Admin over Tailscale	✅ Pass	Separate from public interface
#7 — Webhooks signed	N/A	No webhook handlers in telemetry

---

Part 1 Violations (Culture/Foundation)

Mandatory Error Handling with Unique Codes — VIOLATED

Rule:

Mandatory error handling with unique codes:

• Every if needs an else. The if exists because the condition IS possible
• Use unique error codes: ToLog("ERR-12345: L3 unavailable in decrypt")

Violations Found:

1. Generic error messages (main.go:41, 47, 228, etc.)

   • log.Fatalf("Failed to open operations.db: %v", err)
   • Missing ERR-TELEMETRY-XXX prefix

2. Silent failures (kuma.go:56-58)

   • Kuma push errors completely ignored
   • Comment rationalizes the silence

3. Unchecked errors (main.go:328, 335, 338, 354)

   • Database QueryRow and Exec errors not handled
   • Silent data corruption risk

---

Recommended Fix Priority

Immediate (Before Next Deploy)

1. Issue #002 — Unhandled database errors in updateSpan()

   • Risk: Silent outage tracking failures
   • Impact: Operations blind spot during incidents

2. Issue #003 — Silent Kuma push failure

   • Risk: Monitoring blind spot
   • Impact: "Down" status with no logs explaining why

This Sprint

3. Issue #001 — Missing unique error codes

   • Add ERR-TELEMETRY-XXX codes to all error paths
   • Update test cases to verify codes appear

4. Issue #004 — Unchecked tarpit flush error

   • Minor fix, principle consistency

---

Files Created

• issues/001-missing-error-codes.md — Assignee: Hans
• issues/002-unhandled-db-errors.md — Assignee: Hans
• issues/003-silent-kuma-failure.md — Assignee: Hans
• issues/004-tarpit-flush-error.md — Assignee: Hans

---

Domain Compliance

Per CLAVITOR-AGENT-HANDBOOK.md Section V:

clavis-telemetry — operator telemetry

Owns:

• Heartbeat metrics from POPs to central
• Per-POP system metrics (CPU, memory, disk, vault count)

Must never:

• Send any vault content. ✅ Telemetry is operational, not data.
• Send raw IP addresses of users. ✅ Aggregate counts only.
• Run in community edition by default. ✅ //go:build commercial tag present.

Domain compliance: PASS — The telemetry service properly adheres to its domain constraints. The violations are in error handling hygiene, not in security model violations.

---

Next Steps

1. Hans addresses issues #002 and #003 (High priority)
2. Hans addresses issues #001 and #004 (Medium/Low priority)
3. Yurii reviews PRs before merge
4. Add daily review checklist to telemetry directory per Section III

---

Foundation First. No mediocrity. Ever.