AtlatestRepositorysigil-doc

sigil-doc / tree / testgate-sd-p3.sh

1#!/usr/bin/env bash
2# SD-P3 gate: inline commands in bare prose (review finding B4).
3#
4# Every arm prints its own marker and this script asserts on MARKERS, not on
5# exit status alone. A non-zero exit is equally consistent with a gate that
6# never ran -- 127 not-found, 126 not-executable -- and this estate has been
7# fooled by both.
8#
9# Every count this gate checks for EQUALITY is DERIVED from an artifact rather
10# than written down here. A literal in a check that also exists in the thing
11# checked is the tell for a check that silently stops describing its subject.
13# The exceptions, stated rather than glossed: arm 2's `-ge` thresholds are
14# deliberate LOWER BOUNDS on the denominators, not restatements of them, so
15# they are literals on purpose and adding a node to the fixture cannot
16# desynchronise them.
17set -euo pipefail
18repo_dir="$(cd "$(dirname "$0")/.." && pwd)"
19cd "$repo_dir"
20mkdir -p "$repo_dir/build"
21sigil="${SIGIL_D1_COMPILER:-$repo_dir/../task-sigil-language-readers/build/dev/bin/sigil}"
22redirects="${SIGIL_D1_REDIRECTS:-$repo_dir/dev-redirects.sgl}"
23gate_dir=$(mktemp -d "$repo_dir/build/sd-p3-gate.XXXXXX")
24export SIGIL_REDIRECTS="$redirects"
25export XDG_CACHE_HOME="$gate_dir/cache"
27pass() { printf 'SD_P3_GATE_%02d %s\n' "$1" "$2"; }
28die() { echo "$*" >&2; exit 1; }
30# Every external tool this gate depends on must EXIST. An absent tool silently
31# degrades an assertion into a weaker one that cannot fail.
32for tool in rg git awk sed sha256sum comm sort; do
33 command -v "$tool" >/dev/null || die "$tool is required by this gate"
34done
35test -x "$sigil" || die "dev compiler not found at $sigil"
36test -f src/sigil/doc/private/parser.sgl
37test -f src/sigil/doc/private/author-runtime.sgl
38test -f test/test-prose-runs.sgl
39test -f test/fixtures/sd-p3-bare-prose.sgd
40test -f test/fixtures/sd-p3-wrapped.sgd
41test -f test/transcripts/sd-p3/lowering-before.txt
42test -f test/transcripts/sd-p3/boundary-census-before.txt
43"$sigil" --version
45# DEAD SINCE THE ARM 3 RETIREMENT (2026-08-22), and kept only so that setting
46# `SD_P3_COURSE_DIR` is not silently ignored by a variable that no longer exists.
47# Arm 3 was the only reader; it widened the lowering corpus to the Guile course
48# conversion. Nothing else in this gate uses it, so setting the variable today
49# does nothing. Its successor, `test/gate-sd-p8.sh` arm 5, derives its corpus
50# from the repository rather than taking a directory.
51course_dir="${SD_P3_COURSE_DIR:-}"
53# `test-semantic-structures` reaches `(sigil doc render html)` and therefore
54# `(sigil sxml)`, which this package declares as a git dependency and which is
55# NOT installed in a dev worktree. `test/gate-semantic-structures.sh` supplies it
56# as an explicit load path and so does this gate. Without it the suite fails at
57# module resolution, which looks exactly like a regression and is not one.
58sxml_root="${SIGIL_SXML_ROOT:-$repo_dir/../sigil-sxml}"
59test -d "$sxml_root/src" || die "sigil-sxml source not found at $sxml_root/src"
61run_suite() { # $1 = suite file, $2 = log
62 # NOT `--report`: that flag captures stdout, and these arms assert on
63 # denominators the suites PRINT.
64 if ! setsid -w "$sigil" -L src -L "$sxml_root/src" -L test test "$1" >"$2" 2>&1; then
65 echo "suite $1 exited non-zero" >&2; tail -40 "$2" >&2; return 1
66 fi
67 sed -e 's/\x1b\[[0-9;]*m//g' "$2" >"$2.clean"
70# ---------------------------------------------------------------- ARM 01
71# The prose-run suite. Its test count is derived from the suite source, so
72# adding a test cannot desynchronise this check.
73suite_log="$gate_dir/prose-runs.log"
74run_suite test/test-prose-runs.sgl "$suite_log" || exit 1
75expected=$(rg -c '^\(test "' test/test-prose-runs.sgl)
76rg -q "Tests:\s+${expected} passed \(${expected} total\)" "$suite_log.clean" \
77 || { tail -40 "$suite_log.clean" >&2
78 die "prose-run suite did not report $expected of $expected tests"; }
79rg -q 'All tests passed' "$suite_log.clean" || die "prose-run suite did not report all passing"
80pass 1 "prose-run suite $expected/$expected"
82# ---------------------------------------------------------------- ARM 02
83# The EQUALITY denominators the suite printed. Arm 1 proves the assertions
84# passed; this proves they were made against a non-trivial tree. An equality
85# over two empty trees passes for free.
86compared=$(rg -o 'SD_P3_EQUALITY_COMPARED .*' "$suite_log.clean" | head -1)
87test -n "$compared" || die "the suite printed no equality denominators"
88# BY NAME, NOT BY POSITION. These were positional (`$3`, `$5`, `$7`, `$11`)
89# and adding ONE denominator to the marker -- the url-link count, after the
90# SD-P2 merge -- silently shifted `paragraph` out from under `$11`, so the arm
91# read the url-link count and died with "equality compared only 1 paragraphs".
92# That is the second instance of this exact defect in this gate; the first was
93# an awk field index into the census transcript. A positional read of a
94# self-describing line is a hardcoded count wearing a different hat.
95denominator() { # $1 = name
96 printf '%s\n' "$compared" | sed -n "s/.*[[:space:]]$1[[:space:]]\{1,\}\([0-9]\{1,\}\).*/\\1/p" | head -1
98texts=$(denominator text)
99codes=$(denominator code)
100refs=$(denominator reference)
101paras=$(denominator paragraph)
102urls=$(denominator url-link)
103for n in texts codes refs paras urls; do
104 eval "v=\$$n"
105 test -n "$v" || die "the equality marker carries no '$n' denominator: $compared"
106done
107test "$texts" -ge 6 || die "equality compared only $texts text nodes"
108test "$codes" -ge 2 || die "equality compared only $codes code nodes"
109test "$refs" -ge 1 || die "equality compared only $refs reference nodes"
110test "$paras" -ge 2 || die "equality compared only $paras paragraphs"
111# The cross-phase node: SD-P2's inline url-link, folded by an SD-P3 run.
112test "$urls" -ge 1 || die "equality compared only $urls url-link nodes"
113located=$(rg -o 'SD_P3_LOCATIONS_CHECKED [0-9]+' "$suite_log.clean" | head -1 | awk '{print $2}')
114test -n "$located" || die "the suite printed no location denominator"
115test "$located" -ge 6 || die "locations verified at only $located nodes"
116pass 2 "equality over $texts text / $codes code / $refs reference / $urls url-link / $paras paragraph nodes; locations at $located nodes"
118# THE SUCCESSOR MUST STILL EXIST, AND SOMETHING MUST ASSERT IT.
120# The retirement form deliberately keeps a retired arm PASSING, with a message
121# naming its successor, so that a red is never hidden. **That form has an
122# unstated precondition: the successor is live.** Chain two retirements and the
123# guarantee degrades silently -- a reader follows the pointer and lands on prose
124# explaining what used to be there, while the arm goes on printing a pass.
125# Nothing checked it, and this repository has three retirement notices in flight.
127# A retired arm is a PASSING arm, not a no-op: it still executes, so the check
128# belongs here, immediately before the pass it guards.
130# It pins the successor's CALL SITE (`pass N `) rather than its runtime marker,
131# because the call site is the static artifact a reader greps and the marker only
132# exists once the gate has run. A file-existence check would NOT do: this file's
133# successor lives in a file that still exists; it is the ARM that would be gone.
134successor_arm_exists() { # $1 = file, $2 = arm number
135 test -f "$1" && rg -q "^pass $2 " "$1"
138# ---------------------------------------------------------------- ARM 03
139# RETIRED 2026-08-22 BY THE LEADER, AT SD-P8, UNDER FABLE'S RULING OF
140# 2026-08-11. This arm has NOT silently disappeared and its red has NOT been
141# hidden -- read this before concluding anything.
143# WHAT IT DID. It dumped the complete lowered form sequence for a 16-manuscript
144# corpus and required each one's sha256 to equal a row in
145# `test/transcripts/sd-p3/lowering-before.txt`, a PRE-SD-P3 baseline, except for
146# the manuscripts an independent boundary census predicted would change. It was
147# GREEN on master `0b7c5ca`, measured in a detached worktree before this phase
148# touched anything:
150# SD_P3_GATE_03 lowering byte-identical for 12 of 16 manuscripts;
151# the 4 that changed are exactly the census's
153# So what is being retired is a WORKING arm, not a broken one, and that is the
154# only honest way to describe it.
156# WHY IT IS GONE. Ruling D8 (David, 2026-08-22) moves `@chapter` out of
157# `#lang sigil/doc` into `#lang sigil/doc/book`, which edits the `#lang` line of
158# 17 manuscripts (plus 3 more whose ROOT command changed with the header left
159# alone, and 1 rewritten outright). All 16 of this arm's corpus are among the 17.
160# A header
161# line growing from 16 bytes to 21 moves every byte offset in the manuscript by
162# 5, so every one of those hashes changes -- measured before the migration was
163# written, by editing one fixture and re-running the dump:
165# minimal.sgd before 2b0e9c5dc784d267... after 49bd6d522d9b6f6e...
166# first location ["minimal.sgd" 2:1 byte=16 ...] -> [... byte=21 ...]
168# THE BASELINE CANNOT BE RESCUED, and it is worth saying exactly why, because
169# "just normalise it" is the obvious wrong answer: `lowering-before.txt` stores
170# HASHES, not sections. There is nothing on the BEFORE side to normalise. Nor
171# can it be regenerated -- it is a measurement of a tree at `4dcb41d0`, and
172# regenerating it from a later tree destroys its meaning rather than updating
173# it.
175# A SECOND, INDEPENDENT REASON it could not survive: the dump reaches lowering
176# through the three-argument `parse-document-forms`, which is hardcoded to
177# `sigil-doc-profile` (`src/sigil/doc/private/parser.sgl`). Once that profile's
178# root set is `(article)`, the dump refuses every `@chapter` manuscript whatever
179# its header says. Even a corpus with no header edits at all would have gone
180# red.
182# THE RULING IT IS RETIRED UNDER (Fable, 2026-08-11, recorded in the SD-P1 row
183# of topics/sigil-doc-implementation-plan, applied here by the leader
184# 2026-08-22): a differential gate's meaning is bound to the two endpoints it
185# compares. Standing gates assert invariants; differential gates certify
186# transitions, and a completed transition does not become a standing invariant
187# just because the check is still executable. Retiring it here is legitimate
188# BECAUSE it is ruled and recorded -- laundering is hiding a red, not retiring a
189# differential whose endpoints have moved.
191# SUCCESSOR, and it is strictly stronger: `test/gate-sd-p8.sh` arm 5. It
192# generates BOTH sides in one run -- a detached worktree at SD-P8's own base and
193# the working tree -- so it has no committed baseline to go stale, and it
194# refuses with "baseline superseded" if HEAD stops descending from that base. It
195# compares 22 manuscripts rather than 16 (21 of them in the intersection with the
196# base tree), on a DERIVED population rather than an
197# inherited list, and its claim is not "the hashes match" but "the only thing
198# that changed is the root symbol, and for the 17 header-only manuscripts
199# not even that" -- a hash equality tells you two numbers differ and nothing
200# about why.
202# EVIDENCE PRESERVED: `test/transcripts/sd-p3/lowering-before.txt` and
203# `boundary-census-before.txt` stay in the tree unmodified, and the `test -f`
204# preconditions at the top of this gate still assert they are present. They are
205# SD-P3's reviewed evidence; regenerating them from a later tree would destroy
206# their meaning.
208# STANDING PATTERN, restated for whoever changes lowering next: ship your own
209# before/after differential scoped to your own base, embed the base SHA in the
210# arm, and make a superseded base fail with "baseline superseded -- see ruling"
211# rather than with a bare diff. `test/gate-sd-p8.sh` arm 5 is a worked example.
212successor_arm_exists test/gate-sd-p8.sh 5 \
213 || die "arm 03: this retirement names test/gate-sd-p8.sh arm 5 as its successor, and that arm no longer exists.
214 The retirement form keeps a retired arm PASSING so that a red is never hidden, which assumes the successor is LIVE.
215 With the successor gone this arm asserts nothing and says so to nobody.
216 REMEDY: find what superseded gate-sd-p8 arm 5, re-point the notice above at it, and update this check -- or restore the arm.
217 Do NOT delete this check to make the gate green; that is the failure it exists to catch."
218pass 3 "RETIRED 2026-08-22 at SD-P8 under Fable's 2026-08-11 ruling; superseded by test/gate-sd-p8.sh arm 5 (see comment)"
220# ---------------------------------------------------------------- ARM 04
221# RETIRED 2026-08-22, same disposition and same reasoning as arm 3 above, of
222# which it was a dependent rather than an independent check.
224# WHAT IT DID. It walked arm 3's CHANGED set and required each of those
225# manuscripts to emit between one and `hits` `author-paragraph-run` sites, where
226# `hits` came from the boundary census -- and required every UNCHANGED manuscript
227# to emit none. It was green on `0b7c5ca` alongside arm 3:
229# SD_P3_GATE_04 6 paragraph-run sites, one per non-boundary node,
230# none anywhere else
232# WHY IT CANNOT BE KEPT WHILE ARM 3 GOES. Its input IS arm 3's changed set. With
233# the whole corpus's hashes moved by the header migration, that set becomes every
234# manuscript, and the first one without a census row kills the arm at
235# `die "no census row for $name"`. Keeping it would not preserve its meaning; it
236# would only convert a retirement into a red whose message named the wrong
237# thing.
239# WHAT COVERS THE PROPERTY NOW. The property itself -- that SD-P3's
240# paragraph-run lowering is confined to non-boundary nodes -- is asserted
241# structurally by `test/test-prose-runs.sgl` (arm 1 of this gate, whose count is
242# derived from that suite) and by arm 2's node-by-node equality between the bare
243# and wrapped spellings, neither of which depends on a pre-SD-P3 hash table.
244# `test/gate-sd-p8.sh` arm 5 additionally shows that the D8 migration moved
245# NOTHING in the lowering of the manuscripts SD-P3 cared about, header aside,
246# which is the closest standing equivalent of what this arm certified.
247successor_arm_exists test/gate-sd-p8.sh 5 \
248 || die "arm 04: this retirement names test/gate-sd-p8.sh arm 5 as part of what covers its property, and that arm no longer exists.
249 See the remedy under arm 03 above; the same reasoning applies."
250pass 4 "RETIRED 2026-08-22 at SD-P8 with arm 3, whose changed-set was its only input; property covered by arm 1, arm 2 and test/gate-sd-p8.sh arm 5 (see comment)"
252# ---------------------------------------------------------------- ARM 05
253# Regression: the suites that own the frozen behaviour, with their counts
254# derived from their own sources.
255for suite in test-model test-reader test-root-profile test-passive-parse \
256 test-semantic-structures test-glossary; do
257 log="$gate_dir/$suite.log"
258 run_suite "test/$suite.sgl" "$log" || exit 1
259 n=$(rg -c '^\(test "' "test/$suite.sgl")
260 rg -q "Tests:\s+${n} passed \(${n} total\)" "$log.clean" \
261 || { tail -30 "$log.clean" >&2; die "$suite did not report $n of $n"; }
262done
263pass 5 "D0/D1/D2 model+reader, SD-P1 root-profile, SD-P4 passive, semantic structures and glossary suites green"
265echo "SD_P3_GATE_GREEN"