scripts/convert-swift15-w4dn8.sh

@@ -27,7 +27,8 @@ CALIB=/home/dank/corpora/calib
 OUT=/home/dank/models/rad/qwen4exp-swift15-w4dn8-i8-hc8m.rad
 LOG=/home/dank/logs/swift15_convert.log
 # gate_up ~37.6 + down ~18.8 + PLE 47.7 + trunk/embeddings/head ~10 GiB (all-w4 expert table;
-# the plugin's one-encoding law dropped the block-fp8 down tier -- see the recipe header).
+ # the format assigns ONE encoding per expert table, so a per-tensor block-fp8
+ # down tier cannot be served beside a w4 gate_up tier -- see the recipe header).
 MIN_MIB=${FRANK_SWIFT15_RAD_MIN_MIB:-108000}
 
 # Gate 1: inputs. A missing Gram directory converts UNCALIBRATED with a

scripts/deploy-remote.sh

@@ -947,7 +947,7 @@ deploy_plex() {
     # accepted and then answered with nothing (curl 52, Empty reply) against a
     # perfectly healthy server. Measured 2026-10-02 — the gate burned its full
     # 600s and failed a plex whose https://127.0.0.1:32400/identity answered
-    # 200 in 44 ms the whole time. The same law is why the Caddyfile dials the
+    # 200 in 44 ms the whole time. The same requirement is why the Caddyfile dials the
     # plex upstream over TLS (tests/caddyfile.bats pins it).
     # -k: PMS presents its own self-signed cert on 32400.
     #
@@ -1207,8 +1207,9 @@ deploy_llm_dragoon() {
     # on the FULL container name, which appears in the argv of a manual
     # `podman run --name frank-dragoon-halogen` / `podman wait` but NOT in
     # this deployer's own command line (`bash deploy-remote.sh
-    # frank-dragoon`) — so it cannot shoot itself in the foot (the fleet
-    # pkill law), and it can never match frank-zealot's llama-server.
+    # frank-dragoon`) — so the sweep can never match the deployer's own argv
+    # (`pkill -f` kills the invoker when the pattern appears in the invoker's
+    # own command line), and it can never match frank-zealot's llama-server.
     run_privileged systemctl stop frank-dragoon.service 2>/dev/null || true
     pkill -f 'frank-dragoon-halogen' 2>/dev/null || true
     podman rm -f frank-dragoon frank-dragoon-halogen >/dev/null 2>&1 || true

scripts/derive-protected-experts.py

@@ -2,7 +2,7 @@
 """derive-protected-experts.py — rewrite the recipe's protected-expert section
 from a calibration recording. RUNS ON DANKSERVER (venv: numpy).
 
-The law (docs/MOE-W4.md "Protected experts", restated in the recipe):
+ The protection rule (docs/MOE-W4.md "Protected experts", restated in the recipe):
 an expert whose share of its layer's down-input energy is at least 3% AND
 at least three times its share of the routing is kept bf16; the count must
 be EVEN on each rank's half of the layer (the four-bit GEMM takes the rest

scripts/download-frank-archon-swift15.sh

@@ -14,7 +14,7 @@
 # Fetch uses the vendored scripts/hfget.sh (StillDeadcode's Apache-2.0
 # listing/resume downloader, curl+jq only): per-file size checks against
 # the Hub listing, `-C -` resume, pickle-format duplicates skipped.
-# Verify (default) is the AGENTS.md law in three parts: every listed file
+ # Verify (default) enforces the download contract in three parts: every listed file
 # present with the listed size, the shard count matches the weight-map
 # index, and every shard's sha256 equals the Hub's LFS oid. Verify needs
 # only the public API.

scripts/download-frank-archon.sh

@@ -12,7 +12,7 @@
 # Fetch uses the vendored scripts/hfget.sh (StillDeadcode's Apache-2.0
 # listing/resume downloader, curl+jq only): per-file size checks against
 # the Hub listing, `-C -` resume, pickle-format duplicates skipped.
-# Verify (default) is the AGENTS.md law in three parts: every listed file
+ # Verify (default) enforces the download contract in three parts: every listed file
 # present with the listed size, the shard count matches the weight-map
 # index, and every shard's sha256 equals the Hub's LFS oid. Verify needs
 # only the public API.

scripts/download-frank-dragoon-flashnext.sh

@@ -4,9 +4,10 @@
 # .hgn, the REQUIRED lookup table and the optional vision tower from
 # peonist-ai/halogen-qwen3.8-flash-next (both at the revisions the model
 # card pins), and the flat tokenizer the two repos share. All public, no
-# token — and per the fleet secret law, none would ever touch argv.
+ # token — and a token never rides a command line: argv is readable by every
+ # process on the host through /proc, so a key placed there is a key exposed.
 #
-# The fetch law, same as every sibling script: curl -f (an access error
+ # The fetch discipline, same as every sibling script: curl -f (an access error
 # must not become a "successful" 153-byte artifact), exact byte count from
 # the Hub tree API, LFS sha256 verification, --verify-only to re-check an
 # existing payload without downloading.
@@ -26,7 +27,8 @@
 #   tokenizer/* @e053f488 — byte-identical to the 27B-era tokenizer
 #     already on disk (tokenizer.json LFS
 #     0997f410c57a1f4e53b09e4be8f4a172d90edd9564368fb0847030937229b9f3);
-#     fetched fresh rather than symlinked, per the no-symlink law.
+ #     fetched fresh rather than symlinked, so the payload dir is
+ #     self-contained — every gate and every mount sees real files inside it.
 set -euo pipefail
 
 DEST="${FRANK_DRAGOON_MODEL_DIR:-$HOME/models/halogen-flashnext-v2}"

scripts/download-frank-dragoon-halogen.sh

@@ -1,10 +1,11 @@
 #!/usr/bin/env bash
 # download-frank-dragoon-halogen.sh — fetch frank-dragoon's halogen payload:
 # the qwen3.8-27b .hgn checkpoint and the export tokenizer, from the
-# PUBLIC peonist-ai/halogen-qwen3.8-27b repo (no token — and per the fleet
-# secret law, none would ever touch argv).
-#
-# The fetch law, same as every sibling script: curl -f (an access error
+ # PUBLIC peonist-ai/halogen-qwen3.8-27b repo (no token — and a token never
+ # rides a command line: argv is readable by every process on the host
+ # through /proc, so a key placed there is a key exposed).
+ #
+ # The fetch discipline, same as every sibling script: curl -f (an access error
 # must not become a "successful" 153-byte artifact), exact byte count from
 # the model card, LFS sha256 verification, --verify-only to re-check an
 # existing payload without downloading.

scripts/frank-archon-expert-activity.py

@@ -11,8 +11,8 @@ Tensor extents are DERIVED from consecutive GGUF header offsets — no quant
 type-size table (those are easy to get subtly wrong; a wrong per-element size
 silently under-covers each tensor and dumps tail samples into a junk bucket).
 
-Fleet law this instrument established (2026-09-26, 75 s window, 4 mixed
-streams, 2.7M expert-tensor samples): per-BLOCK read volume is FLAT
+ What this instrument shows (75 s window, 4 mixed streams, 2.7M
+ expert-tensor samples): per-BLOCK read volume is FLAT
 (0.93x-1.08x of mean across all 40 CPU-resident blocks) because MoE top-k
 routing fires every block every token — there are no "most active layers" at
 `-ot` granularity. The real skew is per-EXPERT (top 10% of (block,expert)

scripts/frank-archon.env

@@ -13,7 +13,7 @@
 # +25 % at the full window) while KV beyond the contract buys nothing.
 # Consequence, deliberate: a FOURTH full-height conversation does not fit this
 # pair, and the engine refuses it — it never truncates. See the KV block for the
-# arithmetic and the measured dtype law. The fp8-native payload this file was
+ # arithmetic and the measured per-dtype cost. The fp8-native payload this file was
 # written for is the rollback target and keeps its own trio under the
 # fp8-native runbook.
 #
@@ -124,13 +124,12 @@ FRANK_ARCHON_TP=2
 FRANK_ARCHON_TP_WIRE=wht6
 # Decode slots: THREE, so the served window is a CAPACITY CONTRACT — three
 # concurrent conversations of --max-model-len fit the KV pool (see the KV
-# block below). The "seqs 2 cannot boot" law is NOT radiance's: it was the
-# tcclaviger vLLM fork's torch.compile shape specialization on
-# query_start_loc (ConstraintViolationError, measured 2026-10-02, retired
-# with that runtime). Radiance booted seqs 2 at the fp8-native first boot,
-# and the 2026-10-06 decode sweep measured seqs 2 and 3 statistically tied
-# (30.9-33.1 t/s, inside the +-3% noise floor) — slot count buys concurrency,
-# not speed, so a slot costs KV, never decode.
+ # block below). A runtime that compiles its kernels specialized to the exact
+ # batch shape can refuse a slot count it has never compiled for; a
+ # shape-agnostic engine accepts any count that fits memory. Radiance is the
+ # latter: seqs 2 boots, and measured decode at seqs 2 and 3 is statistically
+ # tied (30.9-33.1 t/s, inside the +-3% noise floor) — slot count buys
+ # concurrency, not speed, so a slot costs KV, never decode.
 # Cost of each extra slot: 110 MiB of per-slot recurrent state inside the KV
 # pool, and the fused TP all-reduce is declared over seqs x (1 + spec) rows —
 # 3 x 3 = 9 here, under the 25-row bound at which the wht6 wire stays EXACT
@@ -255,9 +254,10 @@ FRANK_ARCHON_MAX_BATCHED_TOKENS=2048
 # available with the service loaded).
 FRANK_ARCHON_PREFIX_HOST_MIB=8192
 FRANK_ARCHON_PREFIX_DISK_MIB=65536
-# Frank's pin law: the PLE n-gram table (47.7 GiB) serves from pinned host
-# RAM the cards read. `ram` REFUSES the start if the memlock limit is too
-# small — the unit's LimitMEMLOCK=infinity is the other half of this law.
+ # The PLE n-gram table (47.7 GiB) serves from pinned host RAM the cards
+ # read directly, so it cannot be evicted or page-faulted mid-token. `ram`
+ # placement REFUSES the start if the memlock limit is too small, and the
+ # unit's LimitMEMLOCK=infinity is the matching half of that pairing.
 FRANK_ARCHON_NGRAM_PLACEMENT=ram
 # TTM preflight: the pinned ledger (2 x 44 GiB pools + 47.7 GiB PLE + 8 GiB
 # prefix host = ~147 GiB) rides TTM's shared pages, capped by ttm's

scripts/frank-dragoon.env

@@ -42,10 +42,10 @@
 #   form of the engine's default, so the seam test can pin the product.
 #   KV costs ~28 KiB/position (FLAGS.md) => 524,288 x 28 KiB = 14.0 GiB.
 #   HALOGEN_KV_SLOTS=2 restores the w4b-era shape on this box: the MTP
-#   drafter is NOT slot-locked on this engine (batching and speculation
-#   coexist — DFlash-era slots>1 law does NOT carry over; the card's own
-#   quickstart ships 2 slots WITH the head), so the second slot is
-#   concurrent capacity, not a speculation tax.
+ #   drafter is NOT slot-locked on this engine: some engines silently
+ #   disable drafting the moment a second slot is enabled, this one does not
+ #   (the card's own quickstart ships 2 slots WITH the head), so the second
+ #   slot is concurrent capacity, not a speculation tax.
 #   Memory ledger against the box's 121.2 GiB unified (the n-gram table is
 #   mmap'd page cache beside the checkpoint, not a pinned charge — the
 #   card's own quickstart arithmetic does not bill it):
@@ -88,8 +88,9 @@
 #     before. Kernel needs CONFIG_HSA_AMD_SVM (CachyOS ships it) and
 #     amdgpu.noretry=0 (check at deploy).
 
-# Image: digest-pinned (fetch law: tag pulls silently re-point; the digest
-# is what was qualified). 0.16.2 = the version the model card names as its
+ # Image: digest-pinned (a tag is a mutable pointer — the same tag can
+ # silently deliver different bits — so the digest pins exactly the bits
+ # that were qualified). 0.16.2 = the version the model card names as its
 # quickstart pin; RepoDigest captured at pull on 2026-10-06.
 FRANK_DRAGOON_IMAGE=ghcr.io/peonist-ai/halogen-flash-server@sha256:0c61bf84ac22308a53f5d1ca6b86806702d7039e5ebc51cae4c66621b92fe04a
 # Container identity: kept from the 27B era (unit ExecStop names it).

scripts/frank-zealot.env

@@ -16,7 +16,7 @@
 # custom-quant lock-in like the ROCmFPX era). NO nextn/mtp tensors exist, so
 # in-file MTP is impossible here; SPEC_TYPE=none is forced by the payload.
 #
-# KV rate law: 8 full layers × 4 KV heads × 256 dim = 8,192 elements per
+ # KV rate arithmetic: 8 full layers × 4 KV heads × 256 dim = 8,192 elements per
 # token per cache. f16 K + f16 V = 32,768 B/token = 32 KiB/token, so the
 # 401,408-token pool is 12.25 GiB. The 24 DeltaNet layers cost a fixed
 # recurrent state per SLOT (not per token) — that is why two 200k slots fit

scripts/patches/glm53-dflash-01-aux-hidden-states.patch

@@ -29,7 +29,8 @@
 #     its base SupportsEagleBase (has_own_lm_head, has_own_embed_tokens) -- and
 #     getattr_static()s each one off the instance, breaking on the first miss.
 #     So BOTH wrappers need all three attributes.
-#   * MRO law: INHERITING SupportsEagle3 as a base dies at class creation with
+ #   * Method-resolution order forbids the obvious inheritance: adding
+ #     SupportsEagle3 as a base dies at class creation with
 #     "Cannot create a consistent method resolution order (MRO) for bases ..."
 #     (GLM's wrappers already carry four/five Protocol-derived bases).  The
 #     attribute route avoids the MRO entirely.  Also proven by simulation:

scripts/probe-frank-archon-kv.py

@@ -9,7 +9,8 @@ No scratch container, no mask: the service under test is the service.
 Four probes, in increasing cost:
   A  decode at depth — one ~51k-token chat completion, 512 tokens, greedy.
      Reports the engine's own `timings` (prefill, decode, draft acceptance).
-     The bench law applies: >=128 generated tokens, greedy, real text.
+     Measurement discipline: generate at least 128 tokens (a short run
+     measures first-token noise, not the server), greedy, real text.
   B  the capacity contract — as many CONCURRENT chats of ~197k prompt tokens as
      the deployed `FRANK_ARCHON_MAX_SEQS` (read from the repo env file on this
      host), each carrying a unique marker at its head. All must answer their own

scripts/recipes/qwen4exp-swift15-w4dn8-i8-hc8m.recipe

@@ -1,9 +1,9 @@
 # qwen4exp-swift15-w4dn8-i8-hc8m.recipe -- the Swift 1.5 finetune of Qwen3.8-Flash-Next
 # (ukisai/Swift1.5-Qwen3.8-Flash-Next, BF16 source, 335.3 GiB, key set identical to the official
 # base) as a radiance container for frank-archon: EVERY routed expert -- gate_up AND down --
-# through GPTQ into the w4nl64a8h table. The plugin's one-table-one-encoding law
+ # through GPTQ into the w4nl64a8h table. The format assigns exactly ONE encoding per table
 # ("one table of experts takes one encoding, and only a whole expert kept plain bf16 is served
-# beside it", qwen4exp_fp8 rad_arch_declare) forbids the original split tier (down block-fp8 +
+ # beside it", qwen4exp_fp8 rad_arch_declare — so the original split tier (down block-fp8 +
 # gate_up w4): the served kernel is w4nl64a8h for the whole expert set, bf16 experts beside it.
 # The rest is qwen4exp-w5dn64-i8-hc8m.recipe verbatim: int8 trunk linears, block-fp8 hc mixers
 # and MTP fc, the fixed-scale n-gram table, the 2-bit draft head.
@@ -26,8 +26,8 @@
 # The protected experts, cast to bf16 ahead of both expert rules. THE NAMES BELOW ARE THE BASE
 # CHECKPOINT'S (from its 1M-token recording, qwen4exp-w5dn64-i8-hc8m.recipe) -- a warm start only.
 # The Swift 1.5 finetune's routing distribution is not assumed equal: the derivation step rewrites
-# this section from Swift's OWN calibration recording before this recipe is ever run, by the base's
-# law -- an expert whose share of its layer's down-input energy is at least 3% and at least three
+ # this section from Swift's OWN calibration recording before this recipe is ever run, by the
+ # protection rule -- an expert whose share of its layer's down-input energy is at least 3% and at least three
 # times its share of the routing, an even count on each rank's half of the layer (the four-bit GEMM
 # takes the rest as two equal tables by parity) by adding that half's next most energetic expert.
 # PROTECTED-BEGIN (rewritten from Swift's OWN grams by derive-protected-experts.py)

scripts/serve-frank-dragoon.sh

@@ -70,7 +70,9 @@ fi
 
 # Size-exact gates on all three payload files: a truncated curl exits 0 on
 # some failures and a partial .hgn loads far enough to look alive, so the
-# byte counts from the Hub tree API are the contract (fleet fetch law).
+ # byte counts from the Hub tree API are the contract: curl exits 0 on an
+ # HTTP error and writes the error body as the file, so a truncated download
+ # is caught by size here and never boots.
 ck() {
     # ck <env-name> <path> <expected-bytes>
     if [ ! -f "$2" ]; then

scripts/serve-frank-zealot.sh

@@ -63,8 +63,9 @@ fi
 : "${CACHE_TYPE_K:=f16}"
 : "${CACHE_TYPE_V:=f16}"
 # Speculative decoding is OFF: this Q6_K file carries NO nextn/mtp tensors, so
-# there is no in-file head (the law: MTP is a property of the file, not of the
-# flags). SPEC_TYPE=none strips BOTH speculative flags (flags move as a set);
+ # there is no in-file head — this kind of drafter exists only as tensors
+ # inside the checkpoint file, and no flag can supply one the file lacks.
+ # SPEC_TYPE=none strips BOTH speculative flags (they move as a set);
 # naming a drafter requires SPEC_DRAFT_FILE alongside SPEC_TYPE — the Gemma4
 # assistant on disk is arch gemma4-assistant and cannot drafter-match qwen35.
 : "${SPEC_TYPE:=none}"

scripts/stack-qwen38-official-fp8.py

@@ -298,7 +298,7 @@ def main():
                  and list(dssh) == [(dsh[0] + 127) // 128, (dsh[1] + 127) // 128])
     if not scale_law:
         log(f"ERROR: unexpected expert shapes: gate {gdt}{gsh} scale {gsd}{gssh} "
-            f"down {ddt}{dsh} scale {dsd}{dssh} (scale law 128x128)")
+            f"down {ddt}{dsh} scale {dsd}{dssh} (128x128 block scales)")
         return 2
     shapes = {"ffn2_h": (gsh[0] * 2, gsh[1]), "ffn": (dsh[1],),
               "gs": tuple(gssh), "ds": tuple(dssh)}

tests/frank_archon_unit.bats

@@ -14,7 +14,7 @@
 # half of RAM), the served window is what models.yml must
 # quote, the host-networking contract (no --publish), the image gate on a
 # name@sha256 ref, the .rad payload gate with its size floor, the
-# chat-template override mount, the self-healing law (the run returns before
+ # chat-template override mount, the self-healing requirement (the run returns before
 # the engine is up, so the serve script must wait on the container for
 # Restart=always to mean anything), the deployer's false-green MainPID check,
 # the vendored hfget fetch path (no token for this ungated repo), and the
@@ -136,10 +136,11 @@ nosudo_bin() {
     # Concurrency: 3 slots x the served window is the capacity contract, and
     # the fused TP all-reduce is declared over seqs x (1 + spec) = 9 rows,
     # under the 25-row bound at which the wht6 wire stays bit-exact. The
-    # "seqs 2 cannot boot" law belongs to the retired tcclaviger vLLM fork
-    # (torch.compile query_start_loc constraint, 2026-10-02); radiance booted
-    # seqs 2 in the fp8-native era and the 2026-10-06 sweep had seqs 2 and 3
-    # tied inside the +-3% noise floor — slots buy concurrency, not speed.
+    # "seqs 2 cannot boot" is the failure mode of a runtime that compiles
+    # kernels specialized to the batch shape — it refuses a slot count it has
+    # never compiled for. This engine is shape-agnostic: seqs 2 boots, and
+    # measured decode ties seqs 2 and 3 inside the +-3% noise floor — slots
+    # buy concurrency, not speed.
     grep -q '^FRANK_ARCHON_MAX_SEQS=3$' "$ENV_FILE"
     grep -q '^FRANK_ARCHON_TP=2$' "$ENV_FILE"
     grep -q '^FRANK_ARCHON_TP_WIRE=wht6$' "$ENV_FILE"
@@ -147,8 +148,8 @@ nosudo_bin() {
     # expert_tiered placement: vram_weights + the pinned host pool serve the
     # per-rank resident set TOGETHER, so cutting the VRAM slab to pay for the
     # KV pool moves the pool with it. KV is QUANTIZED fp8 (the engine takes
-    # only bf16|fp8 — no per-tensor K/V split), the PLE n-gram table is pinned
-    # in host RAM per Frank's law.
+    # only bf16|fp8 — no per-tensor K/V split), and the PLE n-gram table is
+    # pinned in host RAM so the cards read it without page-faulting mid-token.
     grep -q '^FRANK_ARCHON_PLACEMENT=expert_tiered$' "$ENV_FILE"
     grep -q '^FRANK_ARCHON_HOST_POOL_MIB=44928$' "$ENV_FILE"
     grep -q '^FRANK_ARCHON_VRAM_WEIGHTS_MIB=[1-9]' "$ENV_FILE"

tests/frank_dragoon_unit.bats

@@ -11,8 +11,9 @@
 # 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
+ # crash-loop class this file exists to kill: both sides are pinned here,
+ # plus the one engine rule the card is emphatic about: HALOGEN_SPEC_ADAPT=0 —
+ # the default
 # adaptive policy silently disables the MTP head per request and HALVES
 # decode.
 #
@@ -111,9 +112,10 @@ 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.
+    # two-slot coupling of the 27B engine — which disabled drafting whenever a
+    # second slot existed — does NOT carry over: 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
@@ -178,8 +180,9 @@ 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).
+    # A truncated curl exit-0 artifact must not boot: curl exits 0 on an HTTP
+    # error and writes the error body as the file, so the Hub's declared byte
+    # count is the contract that catches it.
     podman_stub
     good_env
     run env PATH="$TEST_TMP/bin:$PATH" "${GOOD_ENV[@]}" \
@@ -280,7 +283,7 @@ $(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 budget inside the engine 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