AtlatestRepositorysigil-doc
1
#!/usr/bin/env bash2
# 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 on5
# exit status alone. A non-zero exit is equally consistent with a gate that6
# never ran -- 127 not-found, 126 not-executable -- and this estate has been7
# fooled by both.8
#9
# Every count this gate checks for EQUALITY is DERIVED from an artifact rather10
# than written down here. A literal in a check that also exists in the thing11
# checked is the tell for a check that silently stops describing its subject.12
#13
# The exceptions, stated rather than glossed: arm 2's `-ge` thresholds are14
# deliberate LOWER BOUNDS on the denominators, not restatements of them, so15
# they are literals on purpose and adding a node to the fixture cannot16
# desynchronise them.17
set -euo pipefail18
repo_dir="$(cd "$(dirname "$0")/.." && pwd)"19
cd "$repo_dir"20
mkdir -p "$repo_dir/build"21
sigil="${SIGIL_D1_COMPILER:-$repo_dir/../task-sigil-language-readers/build/dev/bin/sigil}"22
redirects="${SIGIL_D1_REDIRECTS:-$repo_dir/dev-redirects.sgl}"23
gate_dir=$(mktemp -d "$repo_dir/build/sd-p3-gate.XXXXXX")24
export SIGIL_REDIRECTS="$redirects"25
export XDG_CACHE_HOME="$gate_dir/cache"27
pass() { printf 'SD_P3_GATE_%02d %s\n' "$1" "$2"; }28
die() { echo "$*" >&2; exit 1; }30
# Every external tool this gate depends on must EXIST. An absent tool silently31
# degrades an assertion into a weaker one that cannot fail.32
for tool in rg git awk sed sha256sum comm sort; do33
command -v "$tool" >/dev/null || die "$tool is required by this gate"34
done35
test -x "$sigil" || die "dev compiler not found at $sigil"36
test -f src/sigil/doc/private/parser.sgl37
test -f src/sigil/doc/private/author-runtime.sgl38
test -f test/test-prose-runs.sgl39
test -f test/fixtures/sd-p3-bare-prose.sgd40
test -f test/fixtures/sd-p3-wrapped.sgd41
test -f test/transcripts/sd-p3/lowering-before.txt42
test -f test/transcripts/sd-p3/boundary-census-before.txt43
"$sigil" --version45
# DEAD SINCE THE ARM 3 RETIREMENT (2026-08-22), and kept only so that setting46
# `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 course48
# conversion. Nothing else in this gate uses it, so setting the variable today49
# does nothing. Its successor, `test/gate-sd-p8.sh` arm 5, derives its corpus50
# from the repository rather than taking a directory.51
course_dir="${SD_P3_COURSE_DIR:-}"53
# `test-semantic-structures` reaches `(sigil doc render html)` and therefore54
# `(sigil sxml)`, which this package declares as a git dependency and which is55
# NOT installed in a dev worktree. `test/gate-semantic-structures.sh` supplies it56
# as an explicit load path and so does this gate. Without it the suite fails at57
# module resolution, which looks exactly like a regression and is not one.58
sxml_root="${SIGIL_SXML_ROOT:-$repo_dir/../sigil-sxml}"59
test -d "$sxml_root/src" || die "sigil-sxml source not found at $sxml_root/src"61
run_suite() { # $1 = suite file, $2 = log62
# NOT `--report`: that flag captures stdout, and these arms assert on63
# denominators the suites PRINT.64
if ! setsid -w "$sigil" -L src -L "$sxml_root/src" -L test test "$1" >"$2" 2>&1; then65
echo "suite $1 exited non-zero" >&2; tail -40 "$2" >&2; return 166
fi67
sed -e 's/\x1b\[[0-9;]*m//g' "$2" >"$2.clean"68
}70
# ---------------------------------------------------------------- ARM 0171
# The prose-run suite. Its test count is derived from the suite source, so72
# adding a test cannot desynchronise this check.73
suite_log="$gate_dir/prose-runs.log"74
run_suite test/test-prose-runs.sgl "$suite_log" || exit 175
expected=$(rg -c '^\(test "' test/test-prose-runs.sgl)76
rg -q "Tests:\s+${expected} passed \(${expected} total\)" "$suite_log.clean" \77
|| { tail -40 "$suite_log.clean" >&278
die "prose-run suite did not report $expected of $expected tests"; }79
rg -q 'All tests passed' "$suite_log.clean" || die "prose-run suite did not report all passing"80
pass 1 "prose-run suite $expected/$expected"82
# ---------------------------------------------------------------- ARM 0283
# The EQUALITY denominators the suite printed. Arm 1 proves the assertions84
# passed; this proves they were made against a non-trivial tree. An equality85
# over two empty trees passes for free.86
compared=$(rg -o 'SD_P3_EQUALITY_COMPARED .*' "$suite_log.clean" | head -1)87
test -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 the90
# SD-P2 merge -- silently shifted `paragraph` out from under `$11`, so the arm91
# 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 was93
# an awk field index into the census transcript. A positional read of a94
# self-describing line is a hardcoded count wearing a different hat.95
denominator() { # $1 = name96
printf '%s\n' "$compared" | sed -n "s/.*[[:space:]]$1[[:space:]]\{1,\}\([0-9]\{1,\}\).*/\\1/p" | head -197
}98
texts=$(denominator text)99
codes=$(denominator code)100
refs=$(denominator reference)101
paras=$(denominator paragraph)102
urls=$(denominator url-link)103
for n in texts codes refs paras urls; do104
eval "v=\$$n"105
test -n "$v" || die "the equality marker carries no '$n' denominator: $compared"106
done107
test "$texts" -ge 6 || die "equality compared only $texts text nodes"108
test "$codes" -ge 2 || die "equality compared only $codes code nodes"109
test "$refs" -ge 1 || die "equality compared only $refs reference nodes"110
test "$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.112
test "$urls" -ge 1 || die "equality compared only $urls url-link nodes"113
located=$(rg -o 'SD_P3_LOCATIONS_CHECKED [0-9]+' "$suite_log.clean" | head -1 | awk '{print $2}')114
test -n "$located" || die "the suite printed no location denominator"115
test "$located" -ge 6 || die "locations verified at only $located nodes"116
pass 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.119
#120
# The retirement form deliberately keeps a retired arm PASSING, with a message121
# naming its successor, so that a red is never hidden. **That form has an122
# unstated precondition: the successor is live.** Chain two retirements and the123
# guarantee degrades silently -- a reader follows the pointer and lands on prose124
# 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.126
#127
# A retired arm is a PASSING arm, not a no-op: it still executes, so the check128
# belongs here, immediately before the pass it guards.129
#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 only132
# exists once the gate has run. A file-existence check would NOT do: this file's133
# successor lives in a file that still exists; it is the ARM that would be gone.134
successor_arm_exists() { # $1 = file, $2 = arm number135
test -f "$1" && rg -q "^pass $2 " "$1"136
}138
# ---------------------------------------------------------------- ARM 03139
# RETIRED 2026-08-22 BY THE LEADER, AT SD-P8, UNDER FABLE'S RULING OF140
# 2026-08-11. This arm has NOT silently disappeared and its red has NOT been141
# hidden -- read this before concluding anything.142
#143
# WHAT IT DID. It dumped the complete lowered form sequence for a 16-manuscript144
# corpus and required each one's sha256 to equal a row in145
# `test/transcripts/sd-p3/lowering-before.txt`, a PRE-SD-P3 baseline, except for146
# the manuscripts an independent boundary census predicted would change. It was147
# GREEN on master `0b7c5ca`, measured in a detached worktree before this phase148
# touched anything:149
#150
# SD_P3_GATE_03 lowering byte-identical for 12 of 16 manuscripts;151
# the 4 that changed are exactly the census's152
#153
# So what is being retired is a WORKING arm, not a broken one, and that is the154
# only honest way to describe it.155
#156
# WHY IT IS GONE. Ruling D8 (David, 2026-08-22) moves `@chapter` out of157
# `#lang sigil/doc` into `#lang sigil/doc/book`, which edits the `#lang` line of158
# 17 manuscripts (plus 3 more whose ROOT command changed with the header left159
# alone, and 1 rewritten outright). All 16 of this arm's corpus are among the 17.160
# A header161
# line growing from 16 bytes to 21 moves every byte offset in the manuscript by162
# 5, so every one of those hashes changes -- measured before the migration was163
# written, by editing one fixture and re-running the dump:164
#165
# minimal.sgd before 2b0e9c5dc784d267... after 49bd6d522d9b6f6e...166
# first location ["minimal.sgd" 2:1 byte=16 ...] -> [... byte=21 ...]167
#168
# THE BASELINE CANNOT BE RESCUED, and it is worth saying exactly why, because169
# "just normalise it" is the obvious wrong answer: `lowering-before.txt` stores170
# HASHES, not sections. There is nothing on the BEFORE side to normalise. Nor171
# can it be regenerated -- it is a measurement of a tree at `4dcb41d0`, and172
# regenerating it from a later tree destroys its meaning rather than updating173
# it.174
#175
# A SECOND, INDEPENDENT REASON it could not survive: the dump reaches lowering176
# through the three-argument `parse-document-forms`, which is hardcoded to177
# `sigil-doc-profile` (`src/sigil/doc/private/parser.sgl`). Once that profile's178
# root set is `(article)`, the dump refuses every `@chapter` manuscript whatever179
# its header says. Even a corpus with no header edits at all would have gone180
# red.181
#182
# THE RULING IT IS RETIRED UNDER (Fable, 2026-08-11, recorded in the SD-P1 row183
# of topics/sigil-doc-implementation-plan, applied here by the leader184
# 2026-08-22): a differential gate's meaning is bound to the two endpoints it185
# compares. Standing gates assert invariants; differential gates certify186
# transitions, and a completed transition does not become a standing invariant187
# just because the check is still executable. Retiring it here is legitimate188
# BECAUSE it is ruled and recorded -- laundering is hiding a red, not retiring a189
# differential whose endpoints have moved.190
#191
# SUCCESSOR, and it is strictly stronger: `test/gate-sd-p8.sh` arm 5. It192
# generates BOTH sides in one run -- a detached worktree at SD-P8's own base and193
# the working tree -- so it has no committed baseline to go stale, and it194
# refuses with "baseline superseded" if HEAD stops descending from that base. It195
# compares 22 manuscripts rather than 16 (21 of them in the intersection with the196
# base tree), on a DERIVED population rather than an197
# inherited list, and its claim is not "the hashes match" but "the only thing198
# that changed is the root symbol, and for the 17 header-only manuscripts199
# not even that" -- a hash equality tells you two numbers differ and nothing200
# about why.201
#202
# EVIDENCE PRESERVED: `test/transcripts/sd-p3/lowering-before.txt` and203
# `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 are205
# SD-P3's reviewed evidence; regenerating them from a later tree would destroy206
# their meaning.207
#208
# STANDING PATTERN, restated for whoever changes lowering next: ship your own209
# before/after differential scoped to your own base, embed the base SHA in the210
# 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.212
successor_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."218
pass 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 04221
# RETIRED 2026-08-22, same disposition and same reasoning as arm 3 above, of222
# which it was a dependent rather than an independent check.223
#224
# WHAT IT DID. It walked arm 3's CHANGED set and required each of those225
# manuscripts to emit between one and `hits` `author-paragraph-run` sites, where226
# `hits` came from the boundary census -- and required every UNCHANGED manuscript227
# to emit none. It was green on `0b7c5ca` alongside arm 3:228
#229
# SD_P3_GATE_04 6 paragraph-run sites, one per non-boundary node,230
# none anywhere else231
#232
# WHY IT CANNOT BE KEPT WHILE ARM 3 GOES. Its input IS arm 3's changed set. With233
# the whole corpus's hashes moved by the header migration, that set becomes every234
# manuscript, and the first one without a census row kills the arm at235
# `die "no census row for $name"`. Keeping it would not preserve its meaning; it236
# would only convert a retirement into a red whose message named the wrong237
# thing.238
#239
# WHAT COVERS THE PROPERTY NOW. The property itself -- that SD-P3's240
# paragraph-run lowering is confined to non-boundary nodes -- is asserted241
# structurally by `test/test-prose-runs.sgl` (arm 1 of this gate, whose count is242
# derived from that suite) and by arm 2's node-by-node equality between the bare243
# 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 moved245
# 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.247
successor_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."250
pass 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 05253
# Regression: the suites that own the frozen behaviour, with their counts254
# derived from their own sources.255
for suite in test-model test-reader test-root-profile test-passive-parse \256
test-semantic-structures test-glossary; do257
log="$gate_dir/$suite.log"258
run_suite "test/$suite.sgl" "$log" || exit 1259
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"; }262
done263
pass 5 "D0/D1/D2 model+reader, SD-P1 root-profile, SD-P4 passive, semantic structures and glossary suites green"265
echo "SD_P3_GATE_GREEN"