Generate native packet catalog (#46)

codegen/README.md

@@ -31,6 +31,33 @@ copyright attribution are covered by the repository
 [`LICENSE.md`](../LICENSE.md). The generated source manifest repeats each hash
 and license in its header and data table.
 
+## Packet generation
+
+The packet generator tokenizes the pinned `message_template.msg` directly in
+Rust. It preserves source order, all 483 packet names, the 434 low/17 medium/32
+high frequency assignments, 16-bit IDs (including the low-frequency `Fixed`
+IDs), trust and zerocode flags, optional protocol flags, 905 blocks, repetition
+rules, and every field width. Braces, identifiers, numeric values, field kinds,
+prefix widths, duplicate names, and duplicate frequency/ID pairs are validated
+with stable source-located `PGxxx` diagnostics.
+
+[`packet_catalog.rs`](../crates/libremetaverse/src/packet_catalog.rs) is the
+checked-in native output. It contains the public `PacketType` discriminants,
+ordered immutable schema descriptors, name/type/frequency-ID dispatch tables,
+and native construction and sizing implementations for every mapped packet and
+block. Variable blocks start empty, fixed-repeat blocks receive their declared
+number of independently constructed elements, and scalar/vector/UUID fields
+receive the same zero defaults as the golden generator. The generated `Length`
+metadata intentionally preserves the golden generator's variable-block count
+semantics.
+
+Generation also compares all packet, block, field, field-type, and `PacketType`
+entries against the pinned compiled public API catalog. This rejects a template
+parser or naming change even if the emitted Rust would otherwise compile. The
+Rust API compile fixture then compiles every mapped generated member, while the
+packet catalog test exercises representative low/medium/high, fixed, multiple,
+variable, and unknown dispatch behavior.
+
 ## Commands
 
 Regenerate every currently registered Rust output using only checked-in data:
@@ -56,5 +83,5 @@ cargo run -p libremetaverse-codegen -- vendor ../libremetaverse
 Generation uses UTF-8 with an optional BOM, normalizes CRLF/CR to LF, rejects
 NUL input, reports stable `path:line:column: severity[code]` diagnostics, sorts
 manifest records by stable IDs, emits provenance-rich generated headers, and
-always terminates output with one LF. Tests generate twice in memory and
-require byte identity before comparing with the checked-in file.
+always terminates output with one LF. Tests generate both outputs twice in
+memory and require byte identity before comparing with the checked-in files.