[matrixarkai]

The lever

A set or zset member is spelled into its index component by hex::encode, which charges two bytes for every member byte. The component is the only term in a container write that scales with member width — and set and zset are the two models whose marginal cost per user byte is above 1.6x (set 1.671x, zset 1.684x on the incompressible arm) while string, hash and feature all sit at 1.00x. 100% of every model's bytes land in the index leg, and inside it the member is written twice: once as the block key, and once, doubled, as the string the block is filed under.

container_blocks.rs:47 already records the measurement that hex::decode(component) equalled the block bytes on every one of sixty entries. The component does not need to carry the member; it needs to identify it.

This is the reader half, and it has to land on its own

frame_header turns a key-spelling byte it does not recognise into Corrupt — not into an absence. A binary that cannot read the new spelling does not degrade when it meets one, it refuses the block. So every reader has to accept the spelling before any writer is allowed to emit it.

No writer moves in this change. for_kind still answers Hex for a set and ScoreThenMember for a zset, and both hex::encode(&member) sites in execute_on_shard are untouched. Nothing can put byte 4 or 5 into a block, and no component can lead with the tag, so the new branch is unreachable on today's data by construction. no_kind_maps_to_a_new_spelling_yet_so_no_writer_can_emit_one is what holds that.

What is added

• member_component — one tag byte, then the binary-safe name encoding: 1 byte plus the member's own text for a text member, 1 byte plus base64 otherwise.
• member_from_component — reads a component in either spelling, and is the single place that decision is made.
• ElementKeySpelling::Name (4) and ScoreThenMemberName (5), rather than redefining Hex (1) and ScoreThenMember (2). That byte is written into the block, so redefining either would silently reinterpret every block already on disk. New numbers leave them alone and let one store hold both.

The leading tag is load-bearing, not decoration

encode_name returns text unchanged when it can. So an untagged component for the member b"abcd" would be the string "abcd" — which is also valid hex, for two completely different bytes. A component carries no spelling byte of its own, unlike a block, so a reader holding only the string could not tell the two apart and would hand back the wrong member without failing anything. One unconditional tag settles it, because hex::encode emits only [0-9a-f] and can never lead with the tag. a_member_whose_text_is_valid_hex_is_not_confused_with_the_bytes_that_hex_spells drives exactly that case, and the end-to-end selector test uses b"abcd" as its member on purpose.

Where it is wired — eleven production call sites, so it is not inert

All eleven sites that decode a set or zset member component now go through member_from_component:

file	sites
engine/engine_lifecycle.rs	4 — the set and zset removal replay arms, and the set and zset install arms
engine/engine_storage_state.rs	2 — resident_component_address, set and zset
engine.rs	2 — the derived set and zset lookups
engine/container_blocks.rs	3 — select_container_element, plus both directions of the spelling pair

The Hex and ScoreThenMember arms accept both spellings too. That costs nothing and cannot widen them by accident, because a hex string cannot begin with the tag.

Settled by reading, not inferred

zset's component order. There is no order question left: component_from_element_key's ScoreThenMember arm already dropped the score, and says so — "The resident map (shard.zsets) is the score's only copy now; a reader that wants it reads that map, not this string." zset_component is hex::encode(member) and nothing else. The new ScoreThenMemberName arm renders the member alone for the same reason, so there is nothing to order.

A set member is unordered, so set's component spelling is free: the only readers of a set component decode it straight back to the member.

List is deliberately untouched

Its component is sixteen hex digits so that the text sorts in sequence order, and trim_timestamped_series evicts by key order — the spelling there is carrying order, not just identity. It also has the lowest marginal rate of any model at 0.676x, so there is nothing to win. Zero list files in the diff.

Tests

Eight new tests, each pinned by module path in the hard-gate loop. That pinning is not ceremony: the only unfiltered step in this workflow is continue-on-error: true, so it reports and does not gate, and a guard runs only if its name is listed.

The existing spelling ladder grows from four entries to six, so the round trip, the frame decode and the two-element selector all cover the new spellings before any writer emits one. The three counts that floored those loops at the literal 4 are now tied to EVERY_SPELLING.len(), so the next spelling cannot be added without the floor following it.

What is NOT claimed here

No AFTER amplification figure. A reader-only change writes not one byte differently, so it cannot move the rate and none is reported. What is measured at the spelling level is the size of the lever: for a 64-byte text member the component goes from 128 bytes to 65, asserted in the_new_spelling_charges_one_byte_a_member_byte_where_hex_charges_two. Turning that into a marginal-rate number is the writer flip's job, measured on whole_store_cost_per_op's three arms with the payload swept rather than sampled.

Three tests are red on this branch and red identically on its base commit — model_map_container_cost::no_nested_model_map_is_a_hashed_table_and_hashes_carries_the_named_container, the_key_a_block_is_filed_under_inverts_exactly::what_the_entry_restating_its_key_costs_the_shipped_container and round_scale::a_round_walks_the_live_block_set_a_constant_number_of_times. Checked out at the base with nothing of this change present, all three fail the same way; the last one says outright that a round now costs 12 whole-store walks where it measured 13. They are drifted measurement pins on main and not touched by this change.

🤖 Generated with Claude Code