# BIT 值解码

`TableColumn::decode_bit` 解码一个已确认存在、非 NULL 的 BIT（wire type 16）字段。返回 `DecodedBit`，包含无符号 `value: UInt64`、声明的 `bit_length` 和 `bytes_read`。

## 布局与范围

元数据必须恰好有两个字节：第一个是余数位数（0～7），第二个是完整字节数。声明位宽为 `完整字节数 * 8 + 余数位数`，只接受 1～64。零位宽、余数大于 7 或总宽度超出 64 均返回 `InvalidBitMetadata`。

字段按大端读取，长度为 `ceil(bit_length/8)`，没有长度前缀。BIT(9) 的 `01 02` 表示 258；BIT(64) 的八个 FF 表示 18446744073709551615。整个数值始终使用 UInt64，不经过浮点数或有符号转换，也不执行移位 64 位的操作。

数值本身不会表达前导零，`bit_length` 保留声明宽度。例如同为零的 BIT(1) 和 BIT(64) 仍返回不同宽度和消费字节数。BIT(1) 返回整数 0/1，不强制转换为布尔类型。

## 填充位和错误

非整字节字段的第一个字节只使用低 `余数位数` 位，其余高位屏蔽后忽略。上游 unpack 实现同样包含屏蔽未使用位的兼容处理；本接口不因这些位非零而拒绝整个字段。此行为不是将超过声明位宽的比特纳入数值，也不返回这些填充位作为字段数据。

先校验元数据和完整输入长度，再读取字段。不支持的类型返回 `UnsupportedBitColumn`，输入不足返回 `TruncatedColumnValue`。错误保留字段首字节的 `file_offset` 和从零开始的 `column_index`。

`bytes_read` 只包含当前字段，尾部保持未消费。零值不等于 NULL，调用者仍负责行的列存在位图及 NULL 位图；当前不解析行事件。

## 验证与依据

Python 大整数独立构造全部 64 种合法宽度的 188 组样本，另生成七种错误元数据。黑盒测试覆盖全部位宽的零/最大值/非对称模式、部分首字节填充、BIT(1) 的 256 种输入、BIT(64) 高位和最大值、逐字节截断、混合字段与切片。

协议依据固定在 MySQL commit `9fc8d60003b4eee32767c1e30942f222c3508c31` 的 [Field_bit 元数据、pack/unpack 和值读取定义](https://github.com/mysql/mysql-server/blob/9fc8d60003b4eee32767c1e30942f222c3508c31/sql/field.cc)。实现与合成样本独立编写；尚未完成真实 MySQL/Java 交叉验证。