#!/bin/bash
# ==============================================================================================
# ================================== AI Repair Sweep ===========================================
# ==============================================================================================
# PURPOSE
# ─────────────────────────────────────────────────────────────────────────────
# Reads the logs of jobs that finished since the last pass, turns known error shapes into
# findings, probes for a correction, and either writes a proven value or leaves the finding
# for the operator to answer.
# Runs from the watchdog orchestrator. Off unless AI_REPAIR_ENABLED is true.
# ==============================================================================================
# OPERATIONAL MODEL
# ==============================================================================================
# A one-line shim: exec php on ai_repair_sweep.php in the same directory.
# The logic is PHP because everything it needs already is — the conf writer with its backups
# and read-back verification, the findings store, and the probe layer are all functions the
# WebGUI shares. A bash reimplementation would be a second conf writer, which is precisely the
# drift the guarded write path exists to prevent.
#
# There is no post-run hook in Varaverk; nothing fires when a job finishes. The sweep picks up
# completed run records instead, so this is one entry in an orchestrator list rather than a
# call added to forty scripts.
# ==============================================================================================
# DESIGN PRINCIPLES
# ==============================================================================================
# A Shim, Not a Program
#   This file exists only because the scheduler runs shell scripts and the work is PHP.
#   Anything added here would be logic the WebGUI cannot reach, and the operator answering a
#   finding in the browser must take exactly the same path as the sweep that filed it.
#
# Detecting And Repairing Are Separate Trusts
#   AI_REPAIR_ENABLED alone reads logs, files findings and proposes fixes, writing nothing.
#   AI_REPAIR_AUTOFIX_ENABLED is what allows a value to be written, and only ever one a probe
#   has answered on. Both live in master.conf; neither is set by this script.
# ==============================================================================================
# OPERATIONAL SAFEGUARDS
# ==============================================================================================
# Never Fatal
#   Always exits 0 — on a disabled feature, a held lock, or a failed pass. The watchdog
#   orchestrator runs real work either side of this, and a repair sweep must never be the
#   reason a cycle reports failure.
#
# One Sweep At A Time
#   The PHP takes a non-blocking flock. A pass that overruns its slot cannot have a second
#   copy start probing and writing conf underneath it.
#
# Nothing Is Written That Has Not Answered
#   A value reaches conf only after a probe got a response from it. Toggles are never written
#   unattended at all — whether something should be switched on is a decision about intent,
#   and a probe cannot prove intent.
# ==============================================================================================
# CONFIGURATION
# ==============================================================================================
#
# AI_ENABLED                 master switch; nothing here runs without it
# AI_REPAIR_ENABLED          read logs and file findings
# AI_REPAIR_AUTOFIX_ENABLED  allow a proven value to be written unattended
# AI_PROBE_TIMEOUT           seconds a single probe may take
# AI_FINDING_RETAIN_DAYS     how long closed findings are kept
#
# ==============================================================================================
# RUNTIME MODES
# ==============================================================================================
#
# ai_repair_sweep.sh
#     One pass. Files findings, applies proven fixes if autofix is on.
#
# ai_repair_sweep.sh --dry-run
#     Probes and reports what it would do. Writes no conf and does not move the marker, so the
#     same runs are examined again next pass.
#
# ai_repair_sweep.sh --status
#     Both switches, when the last pass ran, and every open finding.
#
# ==============================================================================================

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
php "$SCRIPT_DIR/ai_repair_sweep.php" "$@"