Run frontier MoE models on hardware you already own — pure C, zero deps, experts streamed from disk. Tiny engine, immense model. 🐦
C
feat(tools): add engine evidence preamble and banner helpers
monotophic5cbc549f3feb
diff --git a/c/tests/test_engine_evidence.py b/c/tests/test_engine_evidence.pynew file mode 100644index 00000000..8bcfa5a6--- /dev/null+++ b/c/tests/test_engine_evidence.py@@ -0,0 +1,263 @@+"""tools/engine_evidence.py must parse only exact, in-range preamble text.++Pins the exact banner/loaded text the module accepts, the field ranges it+enforces on both sides of each bound, and the None-vs-raise split in+parse_engine_preamble, so a future edit to the shared parser cannot+silently loosen or break any of its numeric bounds or its exact-text+matching without a local, fast failure.+"""+import unittest++from tools.engine_evidence import (+ PreambleError,+ parse_engine_banner,+ parse_engine_loaded,+ parse_engine_preamble,+)++_BANNER = (+ "== GLM C engine (glm_moe_dsa), cache=8 experts/layer | "+ "compute experts@4-bit dense@8-bit | idot: avx2 =="+)+_LOADED = (+ "loaded in 12.34s | resident dense: 5678.90 MB | layers=32 experts=128 "+ "| MTP ACTIVE (draft=4)"+)+++def _banner(**subs):+ text = _BANNER+ for old, new in subs.items():+ assert old in text, old+ text = text.replace(old, new, 1)+ return text+++def _loaded(**subs):+ text = _LOADED+ for old, new in subs.items():+ assert old in text, old+ text = text.replace(old, new, 1)+ return text+++class ParseEngineBannerTest(unittest.TestCase):+ def test_exact_banner_returns_typed_fields(self):+ fields = parse_engine_banner(_BANNER)+ self.assertEqual(fields, {+ "kind": "BANNER", "cap": 8, "expert_bits": 4, "dense_bits": 8,+ "kernel": "avx2",+ })++ def test_non_string_raises(self):+ with self.assertRaises(PreambleError):+ parse_engine_banner(None)++ def test_unrecognized_text_raises(self):+ with self.assertRaises(PreambleError):+ parse_engine_banner("not a banner at all")++ def test_unknown_kernel_raises(self):+ with self.assertRaises(PreambleError):+ parse_engine_banner(_banner(**{"idot: avx2": "idot: sse4"}))++ def test_trailing_text_rejected(self):+ with self.assertRaises(PreambleError):+ parse_engine_banner(_BANNER + " extra")++ # -- cap: [1, 2**31-1] --++ def test_cap_lower_bound_accepted(self):+ fields = parse_engine_banner(_banner(**{"cache=8": "cache=1"}))+ self.assertEqual(fields["cap"], 1)++ def test_cap_lower_bound_rejected(self):+ with self.assertRaises(PreambleError):+ parse_engine_banner(_banner(**{"cache=8": "cache=0"}))++ def test_cap_upper_bound_accepted(self):+ fields = parse_engine_banner(+ _banner(**{"cache=8": "cache=2147483647"}))+ self.assertEqual(fields["cap"], 2147483647)++ def test_cap_upper_bound_rejected(self):+ with self.assertRaises(PreambleError):+ parse_engine_banner(_banner(**{"cache=8": "cache=2147483648"}))++ # -- expert_bits: [1, 16] --++ def test_expert_bits_lower_bound_accepted(self):+ fields = parse_engine_banner(_banner(**{"experts@4-bit": "experts@1-bit"}))+ self.assertEqual(fields["expert_bits"], 1)++ def test_expert_bits_lower_bound_rejected(self):+ with self.assertRaises(PreambleError):+ parse_engine_banner(_banner(**{"experts@4-bit": "experts@0-bit"}))++ def test_expert_bits_upper_bound_accepted(self):+ fields = parse_engine_banner(_banner(**{"experts@4-bit": "experts@16-bit"}))+ self.assertEqual(fields["expert_bits"], 16)++ def test_expert_bits_upper_bound_rejected(self):+ with self.assertRaises(PreambleError):+ parse_engine_banner(_banner(**{"experts@4-bit": "experts@17-bit"}))++ # -- dense_bits: [1, 16] --++ def test_dense_bits_lower_bound_accepted(self):+ fields = parse_engine_banner(_banner(**{"dense@8-bit": "dense@1-bit"}))+ self.assertEqual(fields["dense_bits"], 1)++ def test_dense_bits_lower_bound_rejected(self):+ with self.assertRaises(PreambleError):+ parse_engine_banner(_banner(**{"dense@8-bit": "dense@0-bit"}))++ def test_dense_bits_upper_bound_accepted(self):+ fields = parse_engine_banner(_banner(**{"dense@8-bit": "dense@16-bit"}))+ self.assertEqual(fields["dense_bits"], 16)++ def test_dense_bits_upper_bound_rejected(self):+ with self.assertRaises(PreambleError):+ parse_engine_banner(_banner(**{"dense@8-bit": "dense@17-bit"}))++ # -- leading-zero handling (no field allows a leading zero on a+ # multi-digit value; a leading zero makes the whole line unrecognized,+ # not merely out of range) --++ def test_leading_zero_digit_rejected(self):+ with self.assertRaises(PreambleError):+ parse_engine_banner(_banner(**{"cache=8": "cache=007"}))++ def test_no_leading_zero_digit_accepted(self):+ fields = parse_engine_banner(_banner(**{"cache=8": "cache=7"}))+ self.assertEqual(fields["cap"], 7)+++class ParseEngineLoadedTest(unittest.TestCase):+ def test_exact_loaded_returns_typed_fields(self):+ fields = parse_engine_loaded(_LOADED)+ self.assertEqual(fields, {+ "kind": "LOADED", "load_s": 12.34, "resident_mb": 5678.90,+ "layers": 32, "experts": 128, "mtp": "ACTIVE", "draft": 4,+ })++ def test_non_string_raises(self):+ with self.assertRaises(PreambleError):+ parse_engine_loaded(1234)++ def test_unrecognized_text_raises(self):+ with self.assertRaises(PreambleError):+ parse_engine_loaded("not a load record")++ # -- layers: [1, 128] --++ def test_layers_lower_bound_accepted(self):+ fields = parse_engine_loaded(_loaded(**{"layers=32": "layers=1"}))+ self.assertEqual(fields["layers"], 1)++ def test_layers_lower_bound_rejected(self):+ with self.assertRaises(PreambleError):+ parse_engine_loaded(_loaded(**{"layers=32": "layers=0"}))++ def test_layers_upper_bound_accepted(self):+ fields = parse_engine_loaded(_loaded(**{"layers=32": "layers=128"}))+ self.assertEqual(fields["layers"], 128)++ def test_layers_upper_bound_rejected(self):+ with self.assertRaises(PreambleError):+ parse_engine_loaded(_loaded(**{"layers=32": "layers=129"}))++ # -- experts: [1, 4096] --++ def test_experts_lower_bound_accepted(self):+ fields = parse_engine_loaded(_loaded(**{"experts=128": "experts=1"}))+ self.assertEqual(fields["experts"], 1)++ def test_experts_lower_bound_rejected(self):+ with self.assertRaises(PreambleError):+ parse_engine_loaded(_loaded(**{"experts=128": "experts=0"}))++ def test_experts_upper_bound_accepted(self):+ fields = parse_engine_loaded(_loaded(**{"experts=128": "experts=4096"}))+ self.assertEqual(fields["experts"], 4096)++ def test_experts_upper_bound_rejected(self):+ with self.assertRaises(PreambleError):+ parse_engine_loaded(_loaded(**{"experts=128": "experts=4097"}))++ # -- exactly two decimal digits on load_s / resident_mb --++ def test_two_decimal_places_accepted(self):+ fields = parse_engine_loaded(_LOADED)+ self.assertEqual(fields["load_s"], 12.34)++ def test_one_decimal_place_rejected(self):+ with self.assertRaises(PreambleError):+ parse_engine_loaded(_loaded(**{"12.34s": "12.3s"}))++ def test_three_decimal_places_rejected(self):+ with self.assertRaises(PreambleError):+ parse_engine_loaded(_loaded(**{"12.34s": "12.345s"}))++ # -- MTP / draft interaction --++ def test_absent_mtp_allows_nonzero_draft(self):+ fields = parse_engine_loaded(+ _loaded(**{"MTP ACTIVE (draft=4)": "MTP absent (draft=5)"}))+ self.assertEqual(fields["mtp"], "absent")+ self.assertEqual(fields["draft"], 5)++ def test_active_mtp_allows_nonzero_draft(self):+ fields = parse_engine_loaded(_LOADED)+ self.assertEqual(fields["mtp"], "ACTIVE")+ self.assertEqual(fields["draft"], 4)++ def test_draft_upper_bound_accepted(self):+ fields = parse_engine_loaded(_loaded(**{"draft=4)": "draft=63)"}))+ self.assertEqual(fields["draft"], 63)++ def test_draft_upper_bound_rejected(self):+ with self.assertRaises(PreambleError):+ parse_engine_loaded(_loaded(**{"draft=4)": "draft=64)"}))++ def test_disabled_multiplexed_requires_zero_draft(self):+ with self.assertRaises(PreambleError):+ parse_engine_loaded(_loaded(+ **{"MTP ACTIVE (draft=4)":+ "MTP DISABLED (multiplexed serve) (draft=4)"}))++ def test_disabled_multiplexed_with_zero_draft_parses(self):+ fields = parse_engine_loaded(_loaded(+ **{"MTP ACTIVE (draft=4)":+ "MTP DISABLED (multiplexed serve) (draft=0)"}))+ self.assertEqual(fields["mtp"], "DISABLED (multiplexed serve)")+ self.assertEqual(fields["draft"], 0)+++class ParseEnginePreambleTest(unittest.TestCase):+ def test_dispatches_to_banner(self):+ self.assertEqual(+ parse_engine_preamble(_BANNER), parse_engine_banner(_BANNER))++ def test_dispatches_to_loaded(self):+ self.assertEqual(+ parse_engine_preamble(_LOADED), parse_engine_loaded(_LOADED))++ def test_unowned_line_returns_none(self):+ self.assertIsNone(parse_engine_preamble("some ordinary log line"))++ def test_banner_prefixed_but_malformed_still_raises(self):+ with self.assertRaises(PreambleError):+ parse_engine_preamble("== GLM C engine but garbled ==")++ def test_loaded_prefixed_but_malformed_still_raises(self):+ with self.assertRaises(PreambleError):+ parse_engine_preamble("loaded in not a valid record")++ def test_non_string_raises(self):+ with self.assertRaises(PreambleError):+ parse_engine_preamble(3.14)+++if __name__ == "__main__":+ unittest.main()diff --git a/c/tools/engine_evidence.py b/c/tools/engine_evidence.pynew file mode 100644index 00000000..cdafd0ff--- /dev/null+++ b/c/tools/engine_evidence.py@@ -0,0 +1,158 @@+"""Helpers for reading what the engine wrote, and for reproducing what it read.++Two unrelated jobs live here because both are shared by more than one+checker: parsing the engine's startup preamble lines, and reproducing the+canonical form of a manifest that the engine binds by digest.++Recognizes the two typed lines the engine prints at startup -- the+"== GLM C engine ..." banner and the following "loaded in ..." record --+and returns their fields as typed values, used by the evidence checkers+that read raw engine stdout. A line that merely looks like one of these+preambles but fails a field check is a bug worth surfacing loudly, so+parsing raises rather than silently skipping.++canonical_manifest_bytes() is the other half: the engine accepts a manifest+saved with either line ending and with or without a final newline, and+digests the normalised form rather than the file as it sits on disk. A+checker that hashed the raw file would disagree with the engine about a+manifest both of them accept, so the rule lives here once and both sides+use it.+"""++import math+import re+++class PreambleError(ValueError):+ """A line resembles an owned engine preamble but is not source-valid."""+++_INT32_MAX = 2**31 - 1+_UINT_TEXT = r"(?:0|[1-9][0-9]*)"+_FIXED2_TEXT = r"(?:0|[1-9][0-9]*)\.[0-9]{2}"+IDOT_KERNELS = (+ "avx512-vnni", "avx-vnni", "avx2", "neon-i8mm", "neon", "vsx",+ "scalar",+)++_BANNER_RE = re.compile(+ r"^== GLM C engine \(glm_moe_dsa\), cache=(?P<cap>" + _UINT_TEXT ++ r") experts/layer \| compute experts@(?P<expert_bits>" + _UINT_TEXT ++ r")-bit dense@(?P<dense_bits>" + _UINT_TEXT ++ r")-bit \| idot: (?P<kernel>" + "|".join(IDOT_KERNELS) + r") ==$")+_LOADED_RE = re.compile(+ r"^loaded in (?P<load_s>" + _FIXED2_TEXT ++ r")s \| resident dense: (?P<resident_mb>" + _FIXED2_TEXT ++ r") MB \| layers=(?P<layers>" + _UINT_TEXT ++ r") experts=(?P<experts>" + _UINT_TEXT ++ r") \| MTP (?P<mtp>ACTIVE|absent|DISABLED \(multiplexed serve\)) "+ r"\(draft=(?P<draft>" + _UINT_TEXT + r")\)$")+++def parse_engine_banner(line):+ """Return typed fields for the exact production "== GLM C engine" banner."""+ if not isinstance(line, str):+ raise PreambleError(f"engine banner is not text: {line!r}")+ match = _BANNER_RE.fullmatch(line)+ if not match:+ raise PreambleError(f"not an exact engine banner: {line!r}")+ cap, expert_bits, dense_bits = map(+ int, match.group("cap", "expert_bits", "dense_bits"))+ if not 1 <= cap <= _INT32_MAX:+ raise PreambleError(f"engine cache outside [1,{_INT32_MAX}]: {cap}")+ if not 1 <= expert_bits <= 16 or not 1 <= dense_bits <= 16:+ raise PreambleError(+ f"engine compute bits outside [1,16]: {expert_bits}/{dense_bits}")+ return {+ "kind": "BANNER", "cap": cap, "expert_bits": expert_bits,+ "dense_bits": dense_bits, "kernel": match.group("kernel"),+ }+++def parse_engine_loaded(line):+ """Return typed fields for the exact "loaded in ..." record that follows the banner."""+ if not isinstance(line, str):+ raise PreambleError(f"engine load record is not text: {line!r}")+ match = _LOADED_RE.fullmatch(line)+ if not match:+ raise PreambleError(f"not an exact engine load record: {line!r}")+ load_s = float(match.group("load_s"))+ resident_mb = float(match.group("resident_mb"))+ layers, experts, draft = map(+ int, match.group("layers", "experts", "draft"))+ mtp = match.group("mtp")+ if not math.isfinite(load_s) or not math.isfinite(resident_mb):+ raise PreambleError("engine load metrics must be finite")+ if load_s < 0 or resident_mb < 0:+ raise PreambleError("engine load metrics must be nonnegative")+ if not 1 <= layers <= 128:+ raise PreambleError(f"engine layers outside [1,128]: {layers}")+ if not 1 <= experts <= 4096:+ raise PreambleError(f"engine experts outside [1,4096]: {experts}")+ if not 0 <= draft <= 63:+ raise PreambleError(f"engine draft outside [0,63]: {draft}")+ if mtp == "DISABLED (multiplexed serve)" and draft != 0:+ raise PreambleError("disabled multiplexed MTP requires draft=0")+ return {+ "kind": "LOADED", "load_s": load_s, "resident_mb": resident_mb,+ "layers": layers, "experts": experts, "mtp": mtp, "draft": draft,+ }+++def parse_engine_preamble(line):+ """Dispatch to the banner/loaded parser by prefix, or return None.++ None means the line is not one of the two owned preambles at all (an+ ordinary log line); a line that starts like one of them but fails to+ parse still raises PreambleError rather than being treated as unowned.+ """+ if not isinstance(line, str):+ raise PreambleError(f"engine preamble is not text: {line!r}")+ if line.startswith("== GLM C engine"):+ return parse_engine_banner(line)+ if line.startswith("loaded in"):+ return parse_engine_loaded(line)+ return None+++class ManifestFormError(ValueError):+ """A manifest cannot be reduced to the canonical form the engine binds."""+++def canonical_manifest_bytes(raw):+ """Return the exact byte stream the engine digests for this manifest.++ The engine reads the file a line at a time, drops the line terminator,+ drops one carriage return in front of it if there is one, and digests the+ remaining record followed by a single newline. A file saved with CRLF+ endings, or without a terminator on its last line, therefore produces the+ same digest as the same content saved as plain newline-terminated text --+ which is what a host editor makes it easy to get wrong.++ Everything else is still refused, and refused here rather than later:+ an empty file, an empty record, a carriage return inside a record, and an+ embedded NUL. Those are not framings of valid content, they are corruption.+ """+ if not isinstance(raw, (bytes, bytearray)):+ raise ManifestFormError(f"manifest is not bytes: {type(raw).__name__}")+ raw = bytes(raw)+ if not raw:+ raise ManifestFormError("manifest is empty")+ if b"\0" in raw:+ raise ManifestFormError("manifest contains a NUL byte")+ records = raw.split(b"\n")+ if records and records[-1] == b"":+ records.pop() # the file ended with its terminator+ if not records:+ raise ManifestFormError("manifest holds no records")+ canonical = []+ for number, record in enumerate(records, 1):+ if record.endswith(b"\r"):+ record = record[:-1]+ if not record:+ raise ManifestFormError(f"manifest line {number} is empty")+ if b"\r" in record:+ raise ManifestFormError(+ f"manifest line {number} has a carriage return inside it")+ canonical.append(record)+ return b"\n".join(canonical) + b"\n"