Specify the binary encoding, so Protocol Buffers is not required

.github/workflows/metanorma.yml

@@ -47,6 +47,12 @@ jobs:
       - name: Check generated schema annex
         run: bundle exec make check-schema
 
+      # Clause 12 of Part 1 states the binary encoding itself. This checks it
+      # against a reference implementation, so the clause cannot drift from
+      # what implementations write.
+      - name: Check the binary encoding
+        run: bundle exec make check-encoding
+
       - name: Check PDF stylesheet
         run: bundle exec ruby scripts/check-stylesheet.rb
 

.github/workflows/pages.yml

@@ -53,6 +53,12 @@ jobs:
       - name: Check generated schema annex
         run: bundle exec make check-schema
 
+      # Clause 12 of Part 1 states the binary encoding itself. This checks it
+      # against a reference implementation, so the clause cannot drift from
+      # what implementations write.
+      - name: Check the binary encoding
+        run: bundle exec make check-encoding
+
       - name: Check PDF stylesheet
         run: bundle exec ruby scripts/check-stylesheet.rb
 

CONTRIBUTING.md

@@ -164,6 +164,36 @@ on anything it does not recognize inside a message body, rather than skipping
 it — so a schema change upstream shows up as a failed run rather than as a
 missing row.
 
+## The binary encoding
+
+Clause 12 of Part 1 specifies the octets of a model directly: the
+variable-length integer, the field key, the four primitive encodings, the two
+forms of a repeated field, and how to skip a field the reader does not know.
+The point of stating it is that the format can be implemented from this
+standard alone. Protocol Buffers is **not** a normative reference — it has no
+citable specification with a stable identifier, which is what made this a
+blocking gap — and an implementation may still be built on a Protocol Buffers
+library, which Clause 12.7 says explicitly.
+
+That only means something if what the clause says is what implementations
+actually write:
+
+```sh
+make check-encoding
+```
+
+`scripts/check-encoding.rb` restates the rules of the clause as a small
+encoder and compares its output, byte for byte, against the Protocol Buffers
+runtime — every scalar type the schema uses, both field key lengths, both
+forms of a repeated field, and the literal octets of the clause's own worked
+examples. The nested-message case is a bootstrap: it builds a message
+descriptor by encoding a `FileDescriptorProto` with its own encoder and hands
+it to the reference library, which rejects it or produces the wrong fields if
+the encoding is wrong.
+
+CI runs it. Edit Clause 12 and the check will tell you whether the edit is
+true.
+
 ## The vendored upstream copy
 
 `upstream/onnx/` is a verbatim copy of the ONNX documentation the draft

Gemfile

@@ -15,6 +15,12 @@ gem "metanorma-generic"
 # every HTML/DOC render fails with `cannot load such file -- sassc-embedded`.
 gem "sassc-embedded"
 
+# Used by scripts/check-encoding.rb as the reference implementation the binary
+# encoding of Clause 12 is checked against. It arrives transitively through the
+# Metanorma toolchain; declared here because the check depends on it directly,
+# and an undeclared dependency has already broken this build twice.
+gem "google-protobuf"
+
 # Used by scripts/generate-operators.rb to convert the upstream operator prose
 # from Markdown to AsciiDoc. Hand-rolling that conversion is not worth it: the
 # prose carries tables, lists, code fences and inline HTML.

Gemfile.lock

@@ -1176,6 +1176,7 @@ PLATFORMS
   x86_64-linux-musl
 
 DEPENDENCIES
+  google-protobuf
   kramdown-asciidoc
   metanorma-cli (~> 1.12)
   metanorma-generic

Makefile

@@ -29,7 +29,7 @@ RUBY       ?= ruby
 SEVERITY   ?= 1
 
 .PHONY: all html doc pdf site lint clean deps check-stylesheet \
-        operators check-operators schema check-schema
+        operators check-operators schema check-schema check-encoding
 
 all: html
 
@@ -79,6 +79,12 @@ schema:
 check-schema:
 	@$(RUBY) scripts/generate-schema.rb --check
 
+# Clause 12 of Part 1 specifies the binary encoding directly, so that the
+# format can be implemented from the standard alone. This checks the rules it
+# states, byte for byte, against a reference implementation.
+check-encoding:
+	@$(RUBY) scripts/check-encoding.rb
+
 # mn2pdf parses the stylesheet itself, and Metanorma exits 0 when that parse
 # fails — producing no PDF while the build looks successful. Check it first;
 # the check needs no fonts, so it also runs where a full PDF render cannot.

README.md

@@ -55,6 +55,7 @@ scripts/check-errors.rb    Gates the build on Metanorma diagnostic severity
 scripts/vendor-onnx-docs.sh  Refreshes the vendored upstream copy
 scripts/generate-operators.rb Generates the operator clauses of Part 2
 scripts/generate-schema.rb  Generates Annex B of Part 1 from the vendored .proto
+scripts/check-encoding.rb  Checks Clause 12's binary encoding against a reference
 upstream/onnx/             Verbatim upstream ONNX docs (complete) + .proto
 .github/workflows/         CI: build HTML + PDF, publish as artifacts
 ```