test: say why the low-margin arm is not redundant (#1082 follow-up)

CHANGELOG.md

@@ -236,6 +236,41 @@ true until the next version shipped.
 
 ### Fixed
 
+- `fsst_margin.sh`'s low-margin arm looks redundant and is not: it falsifies the
+  descriptor reader.
+
+  The three arms across sections 1 and 2b bracket the FSST decision, and the
+  bracket also falsifies `fsst_vectors` itself. Nothing said so, and the
+  low-margin arm reads as a weaker duplicate of the margin-90 one, so it is the
+  obvious thing to delete in a tidy-up.
+
+  Measured by evaluating the arms against a stubbed reader rather than argued:
+
+      reader always returns 0    low-margin RED   margin-90 PASS   codec RED
+      reader always returns >0   low-margin PASS  margin-90 RED    codec PASS
+      the real tree              PASS             PASS             PASS
+
+  `fsst_vectors` parses the encoding descriptor by byte offset,
+  `get_byte(descriptor, 6 + i * 13)`, which is the kind of reader that goes
+  silently wrong on a format change and returns a plausible number. With only the
+  margin-90 arm, a reader stuck at 0 reads as "FSST was dropped" and every arm is
+  green.
+
+  AND THE TWO MARGINS ARE THE GUC'S OWN ENDPOINTS. `columnar_tableam.c:3269`
+  declares it `5, 0, 99`, so the bracket uses the extremes the setting admits
+  rather than an arbitrary low and high. That is what makes each half the
+  strongest form: at margin 0 the keep test is "any compressed win at all keeps
+  FSST", in the GUC's own help text, so `kept == 0` there would mean FSST never
+  helps on this corpus rather than merely not helping enough. Raising it to 5 to
+  simplify the arm would lose that with nothing to show it went.
+
+  Comment only. No check name moves: the sorted name list hashes `62d1b8a49926`
+  before and after.
+
+  Found by @OffgridwithJD reviewing #1082, which had already merged, and the
+  endpoint reading is theirs too. The table is measured rather than argued, and
+  the range was read from the declaration rather than taken on trust.
+
 - The arm named "the visibility-only caller decodes nothing" passed on a tree
   where it decoded (#1077 sweep).
 

test/fsst_margin.sh

@@ -94,6 +94,37 @@ check "the heap mirror has content to compare against" \
 	"$([ -n "$heap_hash" ] && echo yes || echo no)" "yes"
 
 # --- 1. the margin decides ---------------------------------------------------
+#
+# THE THREE ARMS BELOW AND IN 2b BRACKET THE DECISION, and the bracket also
+# falsifies `fsst_vectors` itself. That second property is accidental and worth
+# writing down, because the low-margin arm looks redundant next to the margin-90
+# one and is not:
+#
+#     reader always returns 0    low-margin RED   margin-90 PASS   codec RED
+#     reader always returns >0   low-margin PASS  margin-90 RED    codec PASS
+#     the real tree              PASS             PASS             PASS
+#
+# `fsst_vectors` parses the encoding descriptor by byte offset --
+# `get_byte(descriptor, 6 + i * 13)` -- which is exactly the kind of reader that
+# goes silently wrong on a format change and reports a plausible number. With only
+# the margin-90 arm, a reader stuck at 0 would read as "FSST was dropped" and every
+# arm would be green. Removing the low-margin arm as redundant takes that with it.
+#
+# AND THE TWO MARGINS ARE THE GUC'S OWN ENDPOINTS, not arbitrary low and high
+# values. `columnar_tableam.c:3269` declares it `5, 0, 99` -- default 5, minimum
+# 0, maximum 99 -- so this arm and 2b's bracket the decision with the extremes the
+# setting admits.
+#
+# That is what makes each half the strongest available statement. At margin 0 the
+# keep test is "any compressed win at all keeps FSST", in the GUC's own words, so
+# `kept == 0` here would mean FSST never helps on this corpus rather than merely
+# not helping enough. Raise this to 5 to "simplify" it and that disappears, with
+# nothing to show it went.
+#
+# Found by @OffgridwithJD reviewing #1082, and the endpoint reading is theirs too.
+# The table above is measured rather than argued, by evaluating the arms against a
+# stubbed reader; the range was read from the declaration rather than taken on
+# trust.
 
 load fm_keep 0 "$decide_corpus"
 kept="$(fsst_vectors fm_keep)"