Skip to content

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.py
new file mode 100644
index 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.py
new file mode 100644
index 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"