Sylpheed/tools/port/check-claims

#!/usr/bin/env bash
# Every refuted claim must appear only inside its own correction.
#
#   tools/port/check-claims
#
# 🔴 WHY THIS IS A CHECK AND NOT AN AUDIT. The Decoder's rule -- *grep the corpus
# for the claim, not for the file you were working in* -- found a refuted sentence
# still shipping in this port's `manifest.json`, and a withdrawn one still
# standing in `DECISIONS.md`. Running that by hand finds the instances present on
# the day it is run. It does not stop the next one.
#
# So: a REGISTER. Each row is a claim this corpus has refuted, plus a marker that
# must appear near every occurrence. A hit without its marker fails the run.
#
# ⚠️ Two things learned building it, both from the other agent:
#
#  * a "kept for the record" block STILL ASSERTS. Marking the heading superseded
#    does not mark the sentence a reader lands on, so the marker must sit near
#    the CLAIM, not at the top of the section.
#  * naming a refuted claim keeps it greppable, so this check returns its own
#    corrections as hits -- which is the point. The marker is what distinguishes
#    "quoted while being refuted" from "still asserted".
set -euo pipefail
cd "${PROJECT_DIR:-/work}"
WINDOW=400   # characters either side of a hit in which the marker must appear
fail=0; total_marked=0

# 🔴 THE MARKER IS AN EXPLICIT SENTINEL, NOT A KEYWORD.
#
# The first version matched a per-claim keyword -- "refuted", "WITHDRAWN" -- near
# the hit. Every one of its four failures was a quotation sitting INSIDE a
# correction whose wording happened not to contain the keyword: a table cell
# reading "standing, unmarked", a sentence reading "the real count was ten".
#
# Widening the window or adding synonyms until those passed would have been
# tuning a threshold until the answer came out right, which is the failure this
# corpus has spent a fortnight cataloguing. So the marker is a TOKEN THE AUTHOR
# PLACES: `[refuted]` near any quotation of a registered claim. It cannot be
# satisfied by phrasing, and its absence means exactly one thing.
#
# ⚠️ The cost is honest: every quotation must be marked by hand, and a new
# refuted claim means a new row plus marking its existing quotations. That work
# is the check.
MARKER='[refuted]'
REGISTER=$(cat <<'ROWS'
TAIL of the kept stream
known too fast
only thing making the plate
no loop-point field has been identified
AUDIBLY WRONG AT THE SEAM
1 of 3 streams
six expected DIFFERS
goes against the port
the capture turns out to determine it
COMPOSITED rather than standalone
structural limit, not an unrun experiment
ROWS
)

# ─── THE WITHDRAWAL-TIME HOOK ────────────────────────────────────────────────
# The register enforces claims it KNOWS ABOUT; knowing about them was manual, and
# that is how ~8 claims were withdrawn this session and 0 registered. A sweep
# cannot fix it -- by the time you sweep, the withdrawal is already unpublished.
# The hook fires where the withdrawal is WRITTEN.
#
# A correction in DECISIONS.md has a shape: a heading carrying WITHDRAWN /
# CORRECTION / "refuted". A section like that containing no registered phrase is
# a death argued and never indexed.
#
# ⚠️ The register is passed in the ENVIRONMENT, not inlined. The first version
# pasted the rows into this file's own heredoc -- which made every phrase an
# unmarked quotation, and the checker flagged its own source. A tool that
# violates the rule it enforces by being written is worth a comment.
#
# 🟡 REPORTED, NOT ASSERTED: not every correction retires a CLAIM -- some fix a
# number, a scope, a wrong floor -- and forcing a row for those would push rows
# in to silence the check, the failure this file exists to prevent.
#
# ⚠️ AND IT WILL ALWAYS OVER-REPORT ON WELL-WRITTEN CORRECTIONS. The detection is
# "does this section contain a registered phrase", which requires the correction
# to QUOTE the dead claim. A good correction paraphrases it away: the JP heading
# now reads "does NOT go against the port", which does not contain the registered
# "goes against the port" [refuted] and is flagged despite being registered.
#
# The Decoder's resolution is the right one and costs the correction nothing:
# **the register entry is the verbatim home of the dead phrase; prose paraphrases
# freely.** They are different documents, so the phrase always has one exact
# place to live without any correction having to carry it. What follows for this
# hook is that its candidate list mixes "never registered" with "registered and
# paraphrased", and it cannot separate them -- so the list is a prompt to check,
# never a defect count.
echo
echo "withdrawal-time hook -- correction sections that registered nothing:"
REG="$REGISTER" python3 - <<'HOOK'
import os, re
reg = [r.strip() for r in os.environ["REG"].split("\n") if r.strip()]
doc = open("docs/port/DECISIONS.md").read()
heads = [(m.start(), m.group(0)) for m in re.finditer(r"(?m)^##+ .*$", doc)]
flagged = 0
for i, (pos, head) in enumerate(heads):
    # 🔴 THE FIRST REGEX MATCHED HEADINGS *ABOUT* CORRECTIONS, NOT HEADINGS
    # MAKING THEM -- "withdraw" caught "rather than withdrawing", "refuted"
    # caught a section discussing the register itself. 33 candidates was a
    # measurement of the regex. Narrowed to headings that RETIRE something:
    # a leading WITHDRAWN/CORRECTION/Refuted, or an explicit "is withdrawn".
    if not re.search(r"^#+\s*(?:[^A-Za-z]*\s*)?(WITHDRAWN|CORRECTION|Refuted)\b"
                     r"|\bis withdrawn\b|\bnow refuted\b", head):
        continue
    end = heads[i + 1][0] if i + 1 < len(heads) else len(doc)
    if not any(c in doc[pos:end] for c in reg):
        flagged += 1
        print("  candidate: %s" % head[:92].lstrip("# "))
print("  none -- every correction section names a registered claim" if not flagged
      else "  %d correction section(s) argue a withdrawal the register does not carry" % flagged)
HOOK

while IFS= read -r claim; do
  [ -z "$claim" ] && continue
  hits=0; bad=0; marked=0
  while IFS= read -r loc; do
    [ -z "$loc" ] && continue
    f=${loc%%:*}
    hits=$((hits+1))
    out=$(python3 - "$f" "$claim" "$MARKER" "$WINDOW" <<'PY' 
import sys
f, claim, marker, w = sys.argv[1], sys.argv[2], sys.argv[3], int(sys.argv[4])
s = open(f, encoding="utf-8", errors="ignore").read()
i = n = 0
while True:
    i = s.find(claim, i)
    if i < 0:
        break
    if marker.lower() not in s[max(0, i-w):i+w+len(claim)].lower():
        print("      unmarked in %s at char %d" % (f, i))
        sys.exit(1)
    n += 1
    i += len(claim)
# Every suppression, counted. A checker that can discard an occurrence in silence
# reports the same clean run whether or not a live assertion is hiding among the
# marked ones, and its zero is unfalsifiable. Reached from the loud end here and
# from the quiet end by the Decoder on the same day: their marker language was
# vouching for 8 of 8 mentions, so their 0 was going to be 0 either way.
print(n)
sys.exit(0)
PY
) && marked=$((marked + out)) || { printf '%s\n' "$out"; bad=$((bad+1)); }
  done < <(grep -rl -- "$claim" docs/ crates/ port/ tools/ authored/ 2>/dev/null || true)
  if [ "$bad" -eq 0 ]; then
    printf '  %-42s %d file(s), %d occurrence(s) suppressed\n' "$claim" "$hits" "$marked"
    total_marked=$((total_marked + marked))
  else
    printf '  %-42s 🔴 %d file(s) assert it unmarked\n' "$claim" "$bad"; fail=1
  fi
done <<< "$REGISTER"

echo
printf '  %d occurrence(s) were SUPPRESSED by a neighbouring `%s`.\n' "$total_marked" "$MARKER"
echo "  That number is the size of what this check chose not to look at. A"
echo "  detector that can discard a candidate without saying how many has an"
echo "  unfalsifiable clean run -- its zero reads the same whether or not a live"
echo "  assertion is hiding among the marked ones."
echo
[ $fail -eq 0 ] && echo "every refuted claim appears only inside its correction" \
                || echo "🔴 a refuted claim is still being asserted"
exit $fail