Cognition-OS/docs/rfcs/RFC-0012-Deterministic-Retry-Controller.md

RFC-0012: Deterministic Retry Controller

Status: Draft | Updated: 2026-02-17

Summary

Defines a bounded, deterministic retry mechanism for control-plane policy violations and transient failures.

Goals

• Bounded retries (no infinite loops)
• Transparent ledger recording
• Clear failure modes

API (conceptual)

retry_controller(run_id, max_attempts, policy) -> result

Reference Policy: must-delegate

• Attempt 1: run router normally
• If emit_guarded rejects with POLICY_VIOLATION_MUST_DELEGATE:
  • record policy_violation + retry_scheduled
  • rerun router in strict mode (no free-form output; must spawn immediately)
• Attempt 2: if violation repeats:
  • fail closed with deterministic error message
  • record run_failed

Ledger Events

• retry_scheduled
• retry_started
• retry_exhausted
• run_failed