docs(deltawire): record supervisory control gaps

Author: bigboateng

labs/20-deltawire/GAPS.md

@@ -0,0 +1,50 @@
+# Supervisory generation-control gaps
+
+Status: non-blocking follow-ups to the supervisory-control implementation in PR #123.
+
+The main concept is working: a synthesized supervisor controls compile, stage, verify,
+promote, recovery, and abstention; strict YAML compiles to the existing JSON plan IR;
+an independent evaluator checks the generated bytes; and tested failures preserve the
+previous artifact. The deterministic evaluation and CI require no model calls.
+
+These items are hardening or measurement improvements, not merge blockers.
+
+## Higher-priority hardening
+
+1. **Crash-durable promotion recovery.** Promotion has in-process rollback, but there is
+   no durable journal spanning a process or machine crash between rename, state, and
+   final-receipt writes. A future change should add a small write-ahead promotion record
+   and recovery test matrix.
+2. **Stronger replay closure.** Stored receipts recheck the decision chain and released
+   output. They could additionally bind and revalidate every retained lifecycle artifact,
+   including the compiled plan, reference output, staged output, and engine state.
+3. **Narrow schema TOCTOU exposure.** Freeze schema bytes once and pass that immutable
+   value through staging and verification rather than reopening the source path at later
+   phases.
+4. **Pre-materialization resource bounds.** Reject obviously oversized finite products
+   from their cardinality before expanding rows or compiling a plan.
+
+## Lower-priority completeness
+
+5. Preserve exact integer condition comparisons above JavaScript's safe-integer range;
+   the current condition evaluator uses floating-point numeric comparison.
+6. Reject additional ambiguous YAML scalar spellings if interoperability demands a
+   narrower lexical format.
+7. Increase common-mode independence between the compiler and reference evaluator by
+   splitting any remaining shared low-level expansion helpers.
+8. Add an explicit direct-spec order assertion. Full byte comparison already detects
+   ordering differences, but the source language does not expose order as an assertion.
+9. Harden artifact-path handling against concurrent symlink replacement and other
+   filesystem races beyond the current path and staging checks.
+10. Expand the Pareto report with compiled-plan bytes, timing, and mutation-coverage
+    metrics if those measurements become useful for selecting later AI candidates.
+
+## Explicit boundaries
+
+- The supervisor cannot infer incorrectly approved or unstated intent; external approval
+  or a task oracle remains necessary.
+- The current proof is for the declared finite-state model and tested runtime boundary,
+  not a claim against arbitrary operating-system, hardware, or privileged-adversary faults.
+- The deterministic comparison establishes correctness and interface size only. It does
+  not establish model-token or cost savings without a later controlled AI evaluation.
+