Add BE key decoder for sysio KV support

[heifner]

Summary

Adds abieos_be_key_hex_to_json() — a C API function that decodes the big-endian-encoded key field of a SHiP contract_row_kv_v0 delta to JSON, using the key_names/key_types arrays from the contract's ABI table_def.

This is a standalone utility for any C/C++ SHiP delta consumer that needs to interpret KV table keys without re-implementing CDT's be_key_stream encoding by hand. (hyperion-history-api doesn't use this — it has its own decoder in TypeScript at workers/deserializer.ts:decodeBEKey. The function is here for future or third-party consumers.)

Encoding spec

Mirrors sysio::kv::be_key_stream in wire-cdt:libraries/sysiolib/contracts/sysio/kv_utils.hpp — the encoder is designed so a lexicographic memcmp on the encoded bytes matches the natural ordering of the underlying values, which is why signed integers and floats get sign-flipped:

Type	Encoding
uint8/16/32/64	big-endian raw
int8/16/32/64	big-endian XOR 1<<(N-1)
uint128/int128	big-endian (high uint64 then low uint64); int128 XOR 1<<127
name	big-endian raw uint64
bool	1 byte
float (32-bit)	big-endian; positive XOR 1<<31, negative bitwise NOT
double (64-bit)	big-endian; positive XOR 1<<63, negative bitwise NOT
string / bytes	NUL-escaped: each 0x00 → 0x00 0x01, terminated by 0x00 0x00
checksum160	20 raw bytes (no transform)
checksum256	32 raw bytes
checksum512	64 raw bytes

checksum* types reach be_key_stream via a generic template<DataStream, size_t> operator<<(DataStream&, const fixed_bytes<Size>&) in wire-cdt:libraries/sysiolib/core/sysio/fixed_bytes.hpp that writes the raw bytes via be_key_stream::write(const char*, size_t) — no sign flip, no length prefix.

C API

// Decode big-endian encoded KV key bytes to JSON.
// key_names: JSON array of field names, e.g. '["region","id"]'
// key_types: JSON array of type names, e.g. '["string","uint64"]'
// hex: hex-encoded key bytes
// Returns JSON object, e.g. '{"region":"us-east","id":"42"}'.
// Returns null on error; use abieos_get_error to retrieve error.
const char* abieos_be_key_hex_to_json(abieos_context* context,
                                      const char* key_names,
                                      const char* key_types,
                                      const char* hex);

JSON output conventions

Output matches the rest of abieos:

• uint64/int64 → JSON string ("100") so JS callers don't lose precision via Number
• uint128/int128 → 0x-prefixed lowercase hex string
• checksum* → lowercase hex string (no 0x prefix)
• bytes → lowercase hex string (no 0x prefix)
• Strings get standard JSON escapes for ", \, \n, \r, \t, \b, \f, plus \uXXXX for any other control byte

Robustness improvements over the initial draft

• Replaced the hand-rolled parse_json_string_array with sysio::from_json<std::vector<std::string>>, the same JSON parser the rest of abieos already uses for ABI loading. No more brittle character-by-character state machine.
• Trailing-byte detection: if any bytes remain in the input after all declared fields are decoded, the decoder errors out ("be_key: N trailing byte(s) after decoding declared fields"). Silently dropping bytes hides caller bugs where key_types doesn't match the encoded key.
• Truncated NUL-escape detection: explicit error messages for string (truncated escape), string (no terminator), and string (bad escape) instead of producing garbage.
• Full string escaping in JSON output, including \uXXXX for control bytes — necessary for any string field that legitimately contains binary data.

Test coverage

15 new test cases in src/test.cpp/check_types covering every supported type plus error paths:

• All integer widths and sign variants (uint8/16/32/64, int8/16/32/64)
• uint128/int128 sign-flip round-trip
• name (round-tripped through abieos_string_to_name)
• bool (true/false)
• checksum160, checksum256
• string (simple, embedded NUL via \u0000 escape, empty)
• Composite key (scope:name + sym_code:uint64 — sysio.token's accounts table layout)
• Error: trailing bytes, truncated input, unknown type, mismatched key_names/key_types lengths, empty arrays

All four existing abieos C++ tests still pass.

[dtaghavi]

Review: Add BE key decoder for sysio KV support

Overview

This PR adds abieos_be_key_hex_to_json() — a well-structured C API function that decodes CDT's be_key_stream-encoded KV table keys to JSON. The implementation reuses the existing sysio::from_json parser for input handling and includes solid error detection for trailing bytes, truncated input, and bad NUL escapes. Test coverage is broad across integer/name/bool/checksum/string types.

---

Issues

1. Header doc comment contradicts the implementation (abieos.h)

The example in the header says:
```c
// Returns JSON object, e.g. '{"region":"us-east","id":42}'.
```
But uint64 values are emitted as JSON strings, so the correct example is:
```c
// Returns JSON object, e.g. '{"region":"us-east","id":"42"}'.
```
The PR description gets this right ("uint64/int64 → JSON string"); the header comment needs to match.

---

2. No test coverage for float32/float64

The sign-flip inversion is the most subtle logic in the decoder:
```cpp
// float32
if (bits >> 31) bits ^= (uint32_t(1) << 31);
else bits = ~bits;
```
There are zero test cases for float32 or float64. This is a gap — a bug here is silent since std::to_string(v) won't throw on wrong bit patterns. Suggested cases: a positive value, a negative value, zero, ±infinity, and the boundary where the sign-flip changes branch (+0.0 vs -0.0).

---

3. Truncated-read errors surface internal read width, not the field type

read_be64 always passes "uint64" to be_key_overrun, so decoding a name or int64 field that's truncated produces:

be_key: unexpected end of data reading uint64

…instead of reading name. Same for checksum* types via read_raw_hex. The error is accurate but confusing for API callers. Consider threading the field type through to the error rather than the internal read width.

---

4. Minor: hex_chars is defined twice

"0123456789abcdef" appears as a static const char array in both read_raw_hex and the bytes branch of decode_be_field. A single file-scope constant would remove the duplication.

---

5. Minor: misleading comment in the composite-key test

The composite-key test uses 1397703940 with the comment "SYS" symbol code. 1397703940 = 0x534E5344, which doesn't correspond to "SYS" in ASCII. The round-trip logic is still correct (it exercises a uint64 in a composite key), but the comment is misleading and worth fixing.

---

Strengths

• Replacing the hand-rolled JSON-array parser with sysio::from_json<std::vector<std::string>> is a clear win for correctness and maintainability.
• Trailing-byte detection prevents silently wrong output when key_types doesn't match the actual encoded key — this is the kind of caller bug that would otherwise be very hard to track down.
• std::memcpy for float/double bit-casting is correct and strict-aliasing safe.
• The anonymous namespace properly scopes all helpers.
• NUL-escape error messages (truncated escape, no terminator, bad escape) are precise and actionable.
• The PR description's encoding table is excellent reference material; it should stay in a comment or doc somewhere even after merge.

---

Verdict

Request changes on: fix the header doc comment (#1) and add float32/float64 tests (#2) — both are straightforward. Issues #3–5 are non-blocking but worth a follow-up.

[dtaghavi]

All five issues from the previous review have been addressed — thanks for the thorough follow-through.

What changed:

• Header doc comment — fixed to "id":"42" with an explanatory note about JS precision. Clear and accurate.
• float32/float64 tests — comprehensive: +0.0, -0.0 (branch boundary), ±1.5, ±2.5, plus alias tests for float/double. Verified the encoded bytes independently — all decode to the expected values.
• Truncated-read error messages — type_label is now threaded through all read_be* calls. The new error tests explicitly assert "reading name", "reading int64", "reading float64", "reading checksum256" — exactly the right coverage.
• Duplicate hex_chars — consolidated into a single constexpr char be_key_hex_chars[] at namespace scope. Clean.
• sym_code comment — now correctly derives 5462355 from 'S'|('Y'<<8)|('S'<<16) with an inline explanation of the ASCII packing. No magic numbers.

Approved.