From c6254f2342fec0c27b0d40db2edf4380e3d4dc7f Mon Sep 17 00:00:00 2001 From: Gmer4Lfe Date: Tue, 25 Aug 2026 16:45:39 -0400 Subject: [PATCH] The dev checkers documented themselves under headings nothing else uses --- Plugin/unraid/Tools/ai_log_check.php | 32 +++++++++++-- Plugin/unraid/Tools/ai_log_check.sh | 41 ++++++++++++++++ Plugin/unraid/Tools/conf_widget_check.php | 41 ++++++++++++---- Plugin/unraid/Tools/ui_map_build.php | 58 +++++++++++++++-------- 4 files changed, 139 insertions(+), 33 deletions(-) diff --git a/Plugin/unraid/Tools/ai_log_check.php b/Plugin/unraid/Tools/ai_log_check.php index f2c89a2..9548f8f 100644 --- a/Plugin/unraid/Tools/ai_log_check.php +++ b/Plugin/unraid/Tools/ai_log_check.php @@ -8,10 +8,34 @@ // Reads ai_log_fixtures.txt and this host's /var/log/syslog*. Files nothing, writes nothing, // and calls no part of the sweep beyond vv_ai_syslog_findings() on lines it supplies itself. // -// EXIT -// 0 when every fixture is recognised as written. Precision findings are reported but never -// fail the run: what a real syslog contains is a fact about the machine, not about the -// patterns, and a genuinely failing disk should not turn this into a red test. +// DESIGN PRINCIPLES +// Only recall can fail the run. +// A missed fixture is a fact about the patterns and is always a defect. A precision hit is +// a fact about this machine — a genuinely failing disk should not turn this red, and if it +// did, the honest fix would be to stop having a failing disk rather than to edit a pattern. +// +// Precision is replayed against real history, not a sample. +// The patterns that cause damage are the ones matching ordinary operation, and ordinary +// operation is exactly what a hand-written fixture file never contains. Only the machine's +// own syslog can show what a pattern fires on when nothing is wrong. +// +// The sweep is never invoked, only its matcher. +// vv_ai_syslog_findings() is called on lines this file supplies. Running the real sweep +// would file findings, and a test that has to be cleaned up afterwards stops being run. +// +// OPERATIONAL SAFEGUARDS +// Read-only. Reads ai_log_fixtures.txt and this host's /var/log/syslog*; files no finding, +// writes no store, and touches no conf beyond the enable flag. +// +// Exit 0 when every fixture is recognised as written. Precision findings are reported but +// never fail the run — see DESIGN PRINCIPLES. +// +// RUNTIME MODES +// php ai_log_check.php both checks +// php ai_log_check.php --recall fixtures only +// php ai_log_check.php --precision replay this host's syslog history only +// +// Not scheduled, and deliberately so. Run it after touching VV_AI_SYSLOG_PATTERNS. // ═══════════════════════════════════════════════════════════════════════════════════════════════ require_once dirname(__DIR__) . '/include/ai_repair.php'; diff --git a/Plugin/unraid/Tools/ai_log_check.sh b/Plugin/unraid/Tools/ai_log_check.sh index 457d961..4cee9b9 100755 --- a/Plugin/unraid/Tools/ai_log_check.sh +++ b/Plugin/unraid/Tools/ai_log_check.sh @@ -15,6 +15,47 @@ # # Run it after touching VV_AI_SYSLOG_PATTERNS. Nothing here writes: no findings are filed, no # conf is read for anything but the enable flag, and the sweep is never invoked. +# +# ============================================================================================== +# OPERATIONAL MODEL +# ============================================================================================== +# +# A wrapper. The work is in ai_log_check.php, next to the sweep's own matcher — the patterns and +# vv_ai_syslog_findings() live in include/ai_repair.php, and a bash reimplementation of the +# matching would be a second set of regexes to keep in step with the first. +# +# Flags are forwarded verbatim; nothing is interpreted here. +# +# Not scheduled and in no orchestrator. This is a development check that runs when the patterns +# change, not on a timer — nothing on the running system depends on it. +# +# ============================================================================================== +# DESIGN PRINCIPLES +# ============================================================================================== +# +# Two checks, because the failure modes are opposite. +# Recall catches a pattern that stopped matching; precision catches one that matches too much. +# A single test would catch one and silently permit the other, and the second is the one that +# fills the findings store with noise until the operator stops reading it. +# +# Precision is measured against this machine's real history. +# A hand-written fixture file can show that a pattern matches what it should. Only a real +# syslog can show what it also matches when nothing is wrong. +# +# Only recall fails the run. +# What a real syslog contains is a fact about the machine, not about the patterns. A genuinely +# failing disk should not turn this red. +# +# ============================================================================================== +# OPERATIONAL SAFEGUARDS +# ============================================================================================== +# +# Read-only. No finding is filed, no store is written, and the repair sweep itself is never run +# — only its matcher, on lines this check supplies. +# +# Safe to run on a live host at any time, including one that is currently faulting. It observes +# the syslog it replays and changes nothing about it. +# # ============================================================================================== # RUNTIME MODES # ============================================================================================== diff --git a/Plugin/unraid/Tools/conf_widget_check.php b/Plugin/unraid/Tools/conf_widget_check.php index 701640f..3969279 100644 --- a/Plugin/unraid/Tools/conf_widget_check.php +++ b/Plugin/unraid/Tools/conf_widget_check.php @@ -13,16 +13,39 @@ // php Tools/conf_widget_check.php assertions, then the live summary // php Tools/conf_widget_check.php --list every live field and its inferred control // -// WHY IT ASSERTS AGAINST SNIPPETS AND NOT THE LIVE CONF -// The live conf is the thing being described, so it cannot also be the thing that proves the -// description right — an inference rule that silently stopped matching would keep passing as -// the conf drifted to suit it. The snippets are frozen copies of each convention as written, -// so a rule change that breaks one shows up here rather than as a wrong control on a page. +// DESIGN PRINCIPLES +// Assertions run against snippets, never against the live conf. +// The live conf is the thing being described, so it cannot also be the thing that proves +// the description right — an inference rule that silently stopped matching would keep +// passing as the conf drifted to suit it. The snippets are frozen copies of each +// convention as written, so a rule change that breaks one shows up here rather than as a +// wrong control on a page. // -// WHAT AN INFERENCE IS NOT -// Consistent with confform.php, none of this validates. A number field carrying min and max is -// a courtesy to whoever is typing, not a promise the value is sensible — the consuming script -// still owns that question. +// An inference is a drawing decision, not a validation. +// Consistent with confform.php, none of this validates. A number field carrying min and +// max is a courtesy to whoever is typing, not a promise the value is sensible — the +// consuming script still owns that question. +// +// The live pass reports, it does not assert. +// What this host's master.conf infers to is a description of that file, not a verdict on +// it. Turning the live summary into pass/fail would make an unusual but legitimate +// setting look like a defect. +// +// OPERATIONAL SAFEGUARDS +// Read-only. Parses conf and reports; writes no conf, no store and no page. +// +// Exits non-zero only when a snippet assertion fails, so it can gate a commit without a real +// conf's contents ever being able to break the build. +// +// Never renders. It reports which control would be drawn; the drawing stays in confform.php, +// so this cannot disagree with the page by construction. +// +// RUNTIME MODES +// php Tools/conf_widget_check.php assertions, then the live summary +// php Tools/conf_widget_check.php --list every live field and its inferred control +// +// Hand-run. Not scheduled and in no orchestrator — run it after touching _vv_conf_widget(), +// after adding a conf convention, or when a setting draws as the wrong control. // // DEPENDS ON // include/confform.php _vv_conf_parse_field_range(), vv_conf_key_is_secret() diff --git a/Plugin/unraid/Tools/ui_map_build.php b/Plugin/unraid/Tools/ui_map_build.php index 5e0a6f2..3e43396 100644 --- a/Plugin/unraid/Tools/ui_map_build.php +++ b/Plugin/unraid/Tools/ui_map_build.php @@ -5,31 +5,49 @@ // to reach it. Generated so the assistant can answer "how do I change X" with a path through // the pages instead of an instruction to open master.conf. // -// WHY THE ASSISTANT NEEDS THIS AT ALL -// The retrieval index reads git-tracked files. PHP body markup is not indexed and would be -// useless if it were — a page is a pile of divs, not a description of itself — so the assistant -// has never had any way to know the UI exists. It could name a conf key and nothing more. -// pages/readme/*.md is the one directory the chunker classifies as kind='ui', which is why the -// output lands there and not in docs/. +// DESIGN PRINCIPLES +// The assistant cannot see the UI any other way. +// The retrieval index reads git-tracked files. PHP body markup is not indexed and would be +// useless if it were — a page is a pile of divs, not a description of itself — so the +// assistant has never had any way to know the UI exists. It could name a conf key and +// nothing more. pages/readme/*.md is the one directory the chunker classifies as +// kind='ui', which is why the output lands there and not in docs/. // -// WHY IT IS GENERATED -// A hand-written map is a second description of the pages, and the moment a card moves it -// starts lying with total confidence — which is worse than saying nothing, because the -// assistant will repeat it. Everything here is derived from the same registries the pages -// themselves are built from: VV_SCRIPT_CONF_SECTIONS for what the Scheduler shows per script, -// VV_UI_SECTION_SURFACES for the pages that show sections by subject, and the conf files for -// the settings and their controls. +// Generated, because a hand-written map lies with confidence. +// A second description of the pages starts being wrong the moment a card moves, and that +// is worse than saying nothing, because the assistant will repeat it. Everything here is +// derived from the same registries the pages themselves are built from: +// VV_SCRIPT_CONF_SECTIONS for what the Scheduler shows per script, VV_UI_SECTION_SURFACES +// for the pages that show sections by subject, and the conf files for the settings and +// their controls. +// +// An unreachable section is reported, never dropped. +// A section no page renders is listed at the end rather than silently omitted. A setting +// with no route through the UI is a real finding, and this map is the only thing that +// would ever notice. // // OPERATIONAL MODEL -// Hand-run, and re-run after adding a conf section, a script mapping or a settings surface. -// Writes exactly one file and nothing else. +// Reads the section registries and the conf files, resolves each setting to the page and card +// that renders it, and writes the whole map in one pass. Nothing is merged with what is +// already there — the output is derived entirely from the registries, so a stale entry cannot +// survive a rebuild. // -// php Tools/ui_map_build.php write the map -// php Tools/ui_map_build.php --check report what it would change, write nothing +// OPERATIONAL SAFEGUARDS +// Writes exactly one file, pages/readme/ui-map.md, and nothing else. No conf is modified, no +// page is touched, and the registries it reads are only read. // -// Only sections that are genuinely reachable are listed. A section no page renders is reported -// at the end as unreachable rather than silently omitted — a setting with no route is a real -// finding, and the map is the only place that would notice. +// --check reports what would change and writes nothing, so the map can be verified current in +// a commit without regenerating it. +// +// Generated output only. Nothing hand-edited belongs in ui-map.md — an edit there is lost on +// the next run, which is the correct behaviour for a derived file and the reason the header +// says so. +// +// RUNTIME MODES +// php Tools/ui_map_build.php write the map +// php Tools/ui_map_build.php --check report what it would change, write nothing +// +// Hand-run. Re-run after adding a conf section, a script mapping or a settings surface. // // DEPENDS ON // include/confform.php the section registries, the parser, and the inferred controls