Require explicit VERSION in Integrable trait #97

New Issue

CleverWild · 2026-06-22T15:53:09Z

CleverWild commented

2026-06-22 15:53:09 +00:00

The Integrable trait currently provides a default const VERSION: i32 = 1.
This makes "I didn't think about versioning" and "I deliberately chose version 1"
indistinguishable at the implementation site.

VERSION is the only mechanism that prevents a layout change from producing a
silent MacMismatch (which the system treats as tampering) instead of the
expected PayloadVersionMismatch. If a developer modifies the fields of an
Integrable type and forgets to bump VERSION, existing envelopes will fail
verification with the wrong error is a false tamper signal. The default makes
this mistake easy to introduce and invisible during review.

Remove the default to make VERSION a required constant. Every implementation
must now declare it explicitly, placing the version number physically adjacent
to the struct fields is a natural checkpoint when the layout changes.

All six existing implementations are updated to const VERSION: i32 = 1;.
No behavior changes; the only effect is that future implementors must make a
conscious decision rather than inheriting a silent default.

A deeper fix is deriving VERSION as a structural fingerprint of the Hashable
fields via the macro, so any layout change auto-invalidates envelopes is left
as a follow-up. (#99)

The `Integrable` trait currently provides a default `const VERSION: i32 = 1`. This makes "I didn't think about versioning" and "I deliberately chose version 1" indistinguishable at the implementation site. `VERSION` is the only mechanism that prevents a layout change from producing a silent `MacMismatch` (which the system treats as tampering) instead of the expected `PayloadVersionMismatch`. If a developer modifies the fields of an `Integrable` type and forgets to bump `VERSION`, existing envelopes will fail verification with the wrong error is a false tamper signal. The default makes this mistake easy to introduce and invisible during review. Remove the default to make `VERSION` a required constant. Every implementation must now declare it explicitly, placing the version number physically adjacent to the struct fields is a natural checkpoint when the layout changes. All six existing implementations are updated to `const VERSION: i32 = 1;`. No behavior changes; the only effect is that future implementors must make a conscious decision rather than inheriting a silent default. A deeper fix is deriving VERSION as a structural fingerprint of the Hashable fields via the macro, so any layout change auto-invalidates envelopes is left as a follow-up. (#99)

CleverWild added the

labels 2026-06-22 15:53:09 +00:00