refact(comments): state the mechanism, not the incident

Every comment that invoked a 'law' (50 word-boundary sites across 28
tracked files) now states what is going on and why, in terms that
transfer to any project: gate twins drift until one side greenlights
what the other refuses; a tag re-points while a digest pins; a
restrictive engine behavior belongs to the runtime that imposed it and
must be re-tested, not inherited; a speculative head is tensors in the
file, not a flag; snapshot links dangle where the container resolves
them; exit 0 is a clean stop to systemd, so a self-exiting daemon on
on-failure goes dark reporting success. Event narratives and dates are
gone from these comments; the mechanics carry the argument.

Behavior-identical: bash -n, py_compile, yaml parse, full bats suite
408/408 green. One symbol rename rides along (stack script local
scale_law -> scale_contract, with its log text).
This commit is contained in:
Frank committed 2026-10-14 13:36:40 -07:00
1 parent 65bd5ccea7
commit d4ce76b68b
28 files changed
+195 -164

No files matched your search

+16 -15
View File
@@ -10,11 +10,11 @@
# exact strings the engine reads: the image DIGEST, the checkpoint/n-gram/
# vision file names AND byte counts inside the /models mount, and the
# tokenizer's flat-file shape (a HF cache snapshot's symlinks dangle inside
# the container). A serve gate and a deployer gate that disagree is the
# 2026-10-01 crash-loop; both sides are pinned here, plus the one engine
# law the card is emphatic about: HALOGEN_SPEC_ADAPT=0 — the default
# adaptive policy silently disables the MTP head per request and HALVES
# decode.
# the container). A serve gate and a deployer gate that disagree let a
# deploy pass what the unit would refuse, so both sides are pinned here —
# plus the one engine behavior the card is emphatic about:
# HALOGEN_SPEC_ADAPT=0 — the default adaptive policy silently disables the
# MTP head per request and HALVES decode.
#
# Everything is tested from what an operator or supervisor can observe —
# the command line podman would run, the exit code, the deployer's error
@@ -117,10 +117,11 @@ good_env() {
@test "the head stays on: adaptive spec must stay 0 and the window shape pinned" {
# The card is emphatic: the default adaptive policy turns the MTP head
# off for whole requests after low acceptance and HALVES decode. The
# two-slot law does NOT carry over from the 27B engine — on this line
# batching and speculation coexist (the card's quickstart ships 2
# slots WITH the head), so 2 is concurrent capacity, not a tax.
# off for whole requests after low acceptance and HALVES decode. A
# "slots > 1 disables drafting" restriction belongs to the engine
# generation that imposed it — on this line batching and speculation
# coexist (the card's quickstart ships 2 slots WITH the head), so 2 is
# concurrent capacity, not a tax.
grep -qE '^HALOGEN_SPEC_ADAPT=0$' "$ENV_FILE"
grep -qE '^HALOGEN_KV_SLOTS=2$' "$ENV_FILE"
# The cap/timeout pair is coupled (FLAGS.md table): a request at the
@@ -186,7 +187,7 @@ good_env() {
@test "the serve script refuses a checkpoint of the wrong byte count" {
# A truncated curl exit-0 artifact must not boot; the Hub's byte
# count is the contract (fleet fetch law).
# count is the contract, any other size is a broken artifact.
podman_stub
good_env
run env PATH="$TEST_TMP/bin:$PATH" "${GOOD_ENV[@]}" \
@@ -287,16 +288,16 @@ $(cat "$TEST_TMP/serve.log")"
! grep -q 'PODMAN wait' "$TEST_TMP/serve.log"
}
@test "the shipped env keeps the harness fit law inside the ceiling" {
@test "the shipped env keeps the harness fit margin inside the ceiling" {
# 262144 (the checkpoint's native window) is the per-slot hard ceiling
# (a longer prompt is a 400 naming the limit, never a silent
# truncation). The harness clamps max_tokens = min(45056, 217088 − est
# − 4096), compacts at 85 % of its declared 217088 window, and its
# chars/4 est UNDER-counts the rendered prompt by ~3 % on code/agent
# traffic (measured 4,450 tokens at est 152,938 on 2026-10-07 — with
# window == ceiling, every request over ~146k est was a guaranteed
# 400 before compaction could fire at 85 %). The 45k gap between the
# harness window and the engine ceiling must absorb that error at
# traffic — so a harness window equal to the engine ceiling would make
# every long request a guaranteed 400 before compaction could fire.
# The 45k gap between the harness window and the engine ceiling must
# absorb that error at
# both monotone maxima of est + budget (est ≤ 217088 − 4096):
# full budget at the compaction threshold: 1.03*184524 + 45056
# clamped budget at the clamp's zero point: 1.03*212992 + 0