or re-orders severity tiers (i.e., the issue #29 implementation).
Cross-references: Blocks; informs #29; co-document in
docs/CODEX_CONTEXT.md and event_schema.rs.
Problem Statement. compute_config_version_hash in
apexchainx_calculator/src/lib.rs iterates an internal severities
array:
let severities = [
symbol_short!("critical"),
symbol_short!("high"),
symbol_short!("medium"),
symbol_short!("low"),
];and feeds each threshold_minutes, penalty_per_minute, and
reward_base into a deterministic rolling hash. The iteration
order is load-bearing for backend parity — backends rely on
identical input configs producing identical hashes so they can detect
config drift cheaply. Today nothing in the test suite enforces this
invariant; a contributor re-ordering those four symbol constants, or
moving one of them into a different module during the #8 refactor,
would silently break parity across all backends forever.
There is also no test asserting that adding a 5th severity (e.g.,
the custom severity from #29) — either at init time or at runtime —
does not break the determinism guarantee.
Why It Matters. The whole point of config_version_hash is to
make a config-state-equality check cheap on the backend. A silent
breakage of the iteration-order assumption means backends see
"configs differ" for identical configurations — false-positive
reconciliation rollouts.
Expected Outcome.
- Introduce a
pub fn canonical_severity_order() -> [Symbol; 4] in
lib.rs (or in moduleMap.ts-derived config.rs) that returns
the authoritative canonical ordering.
compute_config_version_hash MUST consume that array as the
iteration source (no inline literal duplicate).- Add a regression test
test_config_version_hash_invariant_under_reorder:
- Hash identical when computed twice.
- Hash changes when ANY field of ANY severity changes.
- Hash is identical if a future contributor mutates
canonical_severity_order in a way that doesn't change the
visible ordering — i.e., asserts that visible ordering, not
internal literal identity, is the invariant.
- Add a unit test pairing each severity with the next in the canonical
order to anchor backward-compatible re-orderings.
- Document the invariant in
event_schema.rs and
docs/CODEX_CONTEXT.md next to the schema spec.
Acceptance Criteria.
- New unit tests live under
tests.rs (or per-module #[cfg(test)]).
- A new check runs in CI: pre-build the hash on a known config and
assert it matches a baseline in
apexchainx_calculator/.config-version-hash.baseline.
- Document explicitly: "Severity iteration order is public ABI.
Re-ordering requires an RESULT_SCHEMA_VERSION bump."
Files: apexchainx_calculator/src/lib.rs,
apexchainx_calculator/src/tests.rs,
docs/CODEX_CONTEXT.md, event_schema.rs.
End of file.
or re-orders severity tiers (i.e., the issue #29 implementation).
Cross-references: Blocks; informs #29; co-document in
docs/CODEX_CONTEXT.mdandevent_schema.rs.Problem Statement.
compute_config_version_hashinapexchainx_calculator/src/lib.rsiterates an internal severitiesarray:
and feeds each
threshold_minutes,penalty_per_minute, andreward_baseinto a deterministic rolling hash. The iterationorder is load-bearing for backend parity — backends rely on
identical input configs producing identical hashes so they can detect
config drift cheaply. Today nothing in the test suite enforces this
invariant; a contributor re-ordering those four symbol constants, or
moving one of them into a different module during the #8 refactor,
would silently break parity across all backends forever.
There is also no test asserting that adding a 5th severity (e.g.,
the custom severity from #29) — either at init time or at runtime —
does not break the determinism guarantee.
Why It Matters. The whole point of
config_version_hashis tomake a config-state-equality check cheap on the backend. A silent
breakage of the iteration-order assumption means backends see
"configs differ" for identical configurations — false-positive
reconciliation rollouts.
Expected Outcome.
pub fn canonical_severity_order() -> [Symbol; 4]inlib.rs(or inmoduleMap.ts-derivedconfig.rs) that returnsthe authoritative canonical ordering.
compute_config_version_hashMUST consume that array as theiteration source (no inline literal duplicate).
test_config_version_hash_invariant_under_reorder:canonical_severity_orderin a way that doesn't change thevisible ordering — i.e., asserts that visible ordering, not
internal literal identity, is the invariant.
order to anchor backward-compatible re-orderings.
event_schema.rsanddocs/CODEX_CONTEXT.mdnext to the schema spec.Acceptance Criteria.
tests.rs(or per-module#[cfg(test)]).assert it matches a baseline in
apexchainx_calculator/.config-version-hash.baseline.Re-ordering requires an
RESULT_SCHEMA_VERSIONbump."Files:
apexchainx_calculator/src/lib.rs,apexchainx_calculator/src/tests.rs,docs/CODEX_CONTEXT.md,event_schema.rs.End of file.