Module cmd_id 

Command ID derivation for the Telepath Command Discovery Protocol.

A cmd_id is a stable 16-bit identifier derived from the command’s human-readable signature. The derivation uses FNV-1a 32-bit hashed over the canonical pre-image, then XOR-folded to 16 bits.

Pre-image

pre-image = name || 0x1F || args_type || 0x1F || ret_type

0x1F (ASCII Unit Separator) cannot appear in Rust identifiers or type paths, so it is collision-free as a field delimiter.

Stand-in for a schema fingerprint

args_type and ret_type are the textual Rust type names as seen by the #[command] proc-macro (syn-derived token strings). This is a textual canonicalization, not a true postcard schema digest:

• Renaming struct Foo { x: u8 } to struct Bar { x: u8 } changes the ID.
• Reordering fields inside Foo does not change the ID.

The ID encodes textual type names, not a structural postcard-schema digest. A future cmd_id v2 could incorporate a real schema hash (see issue #3).

0x0000 reservation

CMD_ID_DISCOVERY (0x0000) is reserved for the Command Discovery Protocol. If the raw hash collides with it, derive_cmd_id rehashes with a 0xFF salt byte appended, producing a deterministic non-zero fallback.

Constants

CMD_ID_FIELD_SEP

Delimiter byte placed between pre-image fields (ASCII Unit Separator, 0x1F).

Functions

derive_cmd_id

Derives a stable 16-bit cmd_id from the command’s textual signature.

fnv1a_16

FNV-1a 32-bit, XOR-folded to 16 bits.