AutoProto 消息分支

本页所有地址均适用于 libtpu-0.0.40-cp314 wheel 中的 libtpu.so（构建 libtpu_lts_20260413_b_RC00，build-id md5 89edbbe81c5b328a958fe628a9f2207d，781,691,048 字节，ELF x86-64 DYN，未 strip；反混淆后的 C++ 符号按原文引用）。其他版本会不同。

摘要

xla::jellyfish::AutoProto oneof 有 30 个分支。标量分支（bool、int64、int32、double 等）携带一个原始值，并由 autoproto-autoor-resolution.md 中的 present-bit 打包逻辑解析。本页负责其他十几个分支，即消息类型分支，其中 AUTO 旋钮解析出的值不是数字，而是完整的子消息：IlpLatencyHidingSchedulerOptions、ShardyOptions、EmitterLearnedCostModelOptions、BundleInstrumentationOptions、TpuCustomCallMemorySpaceSpec、五个 repeated-enum 选项集合，以及两个 repeated-primitive 容器。每个分支都是一个真实的 protobuf 消息，带有自己的 TcParseTableBase（_table_）、自己的默认实例（_globals_）和自己的构造函数。

有两个事实值得为这些分支单独成页。第一，每个消息分支的默认实例都是完整的 proto-zero，并已按字节确认：每个 <Msg>_globals_ 在每个 _table_ 派生字段偏移处读到的都是零，并且每个 <Msg>(Arena*) 构造函数只写入零立即数（类似标量 AUTO→0x000 规则，但作用于整个结构体）。这十二个分支里没有任何 DefaultDebugOptions 风格的非零默认写入器。因此，未设置的（AUTO）消息旋钮会物化为真正空的 config：每个内部 bool=false，int/double=0，enum=first-value(0)，repeated 字段为空，子消息不存在。第二，两个分支在消费者处打破了这条规则，而不是在 proto 中：SparseCoreAssertLevel 将 AUTO 解析为 assert_level::prod() = {values:[ALWAYS]}，TpuCustomCallMemorySpaceSpec 将 AUTO 解析为根据 Target::VmemSizeBytes 定大小的 MsaReservationPolicy。proto 默认值是空的；但实际发布默认值不是。

参考框架是 protobuf 反射。构建过 TextFormat 解析器的读者会熟悉其形状：一个 TcParseTableBase 头，一个按字段号排序的 FieldEntry 数组，每个字段一个 type_card，以及 Reflection::Set*/Add* 系列。libtpu 的变化在于摄入入口（Message::AbslParseFlagImpl，即 JAX flag 值经过的 text:/serialized:/base64: 前缀分派）和每个分支的 ParseFlag 风格（纯 TextFormat、自定义逗号列表、preset/level 列表）。本页结构为：消息分支清单和共享的 _table_/type_card 布局；每个分支的字段字典及其全零默认值；TpuCustomCallMemorySpaceSpec oneof（唯一带内部 oneof 的分支）；text: 形式的 SET 路径（AbslParseFlagImpl → TextFormat → Reflection::Add*）；以及两个覆盖空 proto 的消费者侧默认值。

对重新实现而言，契约是：

消息分支清单和布局：十二个分支类型，每个都有一个 _table_（FieldEntry 数组，每字段一个 type_card）和一个全零 _globals_ 默认实例；type_card 编码扩展了 repeated 基数位和 oneof 位 0x20。
每个分支的字段字典及其空默认值：每个内部字段的编号/名称/proto-type/结构体偏移/type_card，以及默认值对全部十二个分支都是 proto-zero 的证明（构造函数反汇编）。
text: 形式的 SET 路径：Message::AbslParseFlagImpl 格式分派，对刚刚 Clear() 的空实例执行 TextFormat::Parser::ParseFromString，以及 is_repeated（FieldDescriptor 位 0x20）→ Reflection::Add* 与 Set* 的分流，最终落入各个值；再加上三种按分支区分的 ParseFlag 摄入风格，以及两个消费者侧 AUTO 覆盖。


分支数量	12 个消息类型分支（来自 30 分支 `AutoProto` oneof）
共享布局	每个 `<Msg>::_table_` = `TcParseTableBase` + 12 字节 `FieldEntry{u32 off; u32 has_idx; u16 aux_idx; u16 type_card}`，按 field# 排序
默认规则	每个 `<Msg>_globals_` 都是完整 proto-zero；ctor 只写零（无非零默认写入器）
`type_card`（消息）	singular message `0x0416`；oneof-member message `0x0436`（`= 0x0416 \| 0x20`）
最深树	`EmitterLearnedCostModelOptions`：9 个字段，包括一个 8 字段 `LearnedCostModelClientOptions` 子消息（兄弟文件描述符）
内部 oneof	`TpuCustomCallMemorySpaceSpec.policy`：`{msa_reservation_policy, hbm_policy}` 互斥
SET 入口	`proto2::Message::AbslParseFlagImpl @ 0x20ef2120`：`text:`/`serialized:`/`base64:` 分派
text: 摄入	`TextFormat::Parser::ParseFromString @ 0x20efd420` → `ConsumeFieldValue @ 0x20f07a60`（is_repeated 位 `0x20` → `Add` 与 `Set`）
消费者覆盖	`assert_level::prod() @ 0x1db1d8a0` → `[ALWAYS]`；`ResolveMemorySpaceSpec @ 0x11036320` → 定大小到默认 scoped VMEM 的 MSA
描述符	`tpu_compilation_environment.proto` FDP `@ 0xbfa6060`（11 个分支）；`emitter_learned_cost_model_options.proto` FDP `@ 0xbfc7bc0` + `learned_cost_model_client_options.proto` FDP `@ 0xbfc8160`
置信度	CONFIRMED（字节锚定 vs 反编译），除非某行或标注另有说明

1. 消息分支清单

目的

三十个 AutoProto oneof 分支中有十二个是消息类型（type_card family 0x04xx），不是标量。当由这些分支之一支持的 TCE 旋钮保持 AUTO（oneof_case_ == 0，见 autoproto-autoor-resolution.md）时，消费者访问器（解析页上的 Idiom E）会构造该分支的空默认实例：IlpLatencyHidingSchedulerOptions(arena)、ShardyOptions(arena) 等。因此，未设置消息旋钮的值就是该空实例中包含的内容。本节固定共享布局；§2 给出每个分支的字段字典，并证明默认值为空。

共享的 `_table_` 布局

每个消息分支都是一个生成的 protobuf 消息，带标准 TcParseTableBase 头和一个 FieldEntry 数组；这与 TCE 主表和 AutoProto oneof 自身使用的布局相同（第三个独立字节确认，说明 TcParser 布局在这个 proto 家族中一致）。

text

<Msg>::_table_   (TcParseTableBase, in .data.rel.ro)
  +0x00  u16  has_bits_offset       ── message 中 _has_bits_ word 的字节偏移
  +0x04  u32  max_field_number
  +0x10  u16  field_entries_offset  ── FieldEntry 数组在此 table 内的字节偏移
  +0x14  u16  num_field_entries
  +0x16  u16  num_aux_entries       ── aux 子表指针数量（用于 message 字段）
  +0x18  u32  aux_offset            ── aux 指针数组在此 table 内的字节偏移

FieldEntry  (每项 12 字节，按字段号升序排序)
  +0x00  u32  offset      ── 字段在 message C++ 结构体内的偏移
  +0x04  u32  has_idx     ── singular 的 has-bit index (128..)；oneof member 的 oneof _case_ word 偏移
  +0x08  u16  aux_idx     ── aux table 索引（message 字段 → 嵌套 <Sub>::_table_）
  +0x0a  u16  type_card   ── proto type + cardinality（见下表）
```text

`type_card` 编码在 [autoproto-autoor-resolution.md](autoproto-autoor-resolution.md) 的标量表基础上扩展了 repeated 基数位（低 3 位：singular `=1`，repeated `=2`），并为 oneof member 扩展了 `0x20` oneof 位：

```text
singular : bool 0x0011  int32 0x1091  int64 0x10d1  uint64 0x08d1  double 0x18d3
           float 0x18b3  string 0x0c15  enum 0x1891  message 0x0416
repeated : enum 0x18a2   int64 0x10e2  string 0x0d25
oneof    : message 0x0436   (= singular message 0x0416 | 0x20)   — 仅 TpuCustomCallMemorySpaceSpec

清单

十二个消息分支及其 parse table、默认实例和构造函数。flag-name 列是由每个分支支持的 TCE 旋钮（从 registry-mediated-flags.md 和 tce-field-offsets-defaults.md 交叉得到）；一个消息类型可以支持多个 flag。

分支	`_table_`	`_globals_`	ctor	字段	TCE flag
`IlpLatencyHidingSchedulerOptions`	`0x21cfa308`	`0x223c8790`	`0x1db24d00`	6	`xla_tpu_ilp_latency_hiding_scheduler_options`
`CostModelFlagOptions`	`0x21cfa170`	`0x223c87e8`	`0x1db23d40`	2 (repeated enum)	`xla_msa_cost_model_options`, `xla_tpu_fusion_cost_model_options`, `xla_tpu_latency_hiding_scheduler_cost_model_options`
`SparseCoreOffloadingOptions`	`0x21cfa110`	`0x223c85d8`	`0x1db23780`	1 (repeated enum)	`xla_tpu_sparse_core_offloading_options`
`ShardyOptions`	`0x21cfa260`	`0x223c8650`	`0x1db24940`	3	`xla_shardy_options`
`EmitterLearnedCostModelOptions`	`0x21cff9a8`	`0x223c9710`	`0x1db63f20`	9 (+ 8-field sub-msg)	`xla_tpu_emitter_learned_cost_model_options`
`AccumulatorTransformations`	`0x21cf9c30`	`0x223c88d8`	`0x1db20fe0`	1 (repeated enum)	`xla_tpu_accumulator_transformations`
`SparseCoreAssertLevel`	`0x21cfa550`	`0x223c8608`	`0x1db252e0`	1 (repeated enum)	`xla_sc_assert_level`
`BundleInstrumentationOptions`	`0x21cfa5b0`	`0x223c8860`	`0x1db258a0`	3	`xla_tpu_bundle_instrumentation_options`
`TpuCustomCallMemorySpaceSpec`	`0x21cfa708`	`0x223c8920`	`0x1db25fa0`	2 (oneof, +nested)	`xla_tpu_tpu_custom_call_memory_space_spec`
`BufferContentsSanitizerConfig`	`0x21cf9f58`	`0x223c8890`	`0x1db23040`	2	TCE field #623（按 oneof map 为分支 10）
`RepeatedStrings`	`0x21cf9d18`	—	—	1 (repeated string)	`xla_explicit_disable_passes` (#900), `xla_explicit_enable_passes` (#901), `xla_tpu_enable_mosaic_emitters`, `xla_tpu_block_summary_split_specs`
`RepeatedIntegers`	`0x21cf9da0`	—	—	1 (repeated int64)	`xla_tpu_distributed_hash_moduli`, `xla_tpu_reserved_sparse_cores`

NOTE — 第十三个 AutoOr<message> 类型 CostModelLoggingOptions（_globals_ @ 0x223c87c8，ctor @ 0x1db24600，2 个 bool 均默认 false）不是 30 个 TCE oneof 分支之一；它是非 TCE 的 xla_tpu_impure_cost_model_logging_options flag，此处仅为完整性而解码。其非 TCE resolver/consumer 未追踪（LOW）。
GOTCHA — 父级 AutoProto::_table_（@ 0x21cfa788）和各分支 table 在 .data.rel.ro 中相邻，因为这些 proto 共享一个 translation unit。交叉引用某个分支时应使用其符号（<Msg>::_table_），不要凭地址目测；分支 table、AutoProto table 和 1121 字段 TCE 主表（@ 0x21cfa9e0）交错位于同一地址带。

2. 每个分支的字段字典和空默认值

目的

对每个分支，给出内部字段字典（编号 / 名称 / proto-type / struct-offset / type_card）以及每个字段经字节确认的默认值。两个独立字节来源已逐字段交叉验证，零处不一致：生成的 C++ <Msg>::_table_ FieldEntry 数组（给出偏移和 type_card）以及雕刻出的 FileDescriptorProto（给出字段编号、名称和 proto-type）。_table_ 是二进制结构体布局；FDP 是人类可读字段名；二者合起来就是完整字典。

默认值列在全部十二个分支上是一致的：AUTO ⇒ 空默认实例 ⇒ 每字段 proto-zero。每个 <Msg>_globals_ 都在其 _table_ 偏移处读取过（每个字节为零），每个 <Msg>(Arena*) 也都反汇编确认只执行零写入。

全零默认值证明

IlpLatencyHidingSchedulerOptions(Arena*) @ 0x1db24d00 是标准形状：arena 写入 metadata，vtable，然后对字段区域做一次向量化清零：

function IlpLatencyHidingSchedulerOptions(this, Arena*):   // 0x1db24d00
    this[+0x08] = arena                  // InternalMetadata tagged ptr
    this[+0x00] = &vtable+0x10
    *(ymm*)(this + 0x10) = 0             // vxorps/vmovups — zero 32 B (has-bits + fields)
    *(u32*)(this + 0x2f) = 0             // zero the field tail
    return                               // NO non-zero immediate store anywhere
```text

十二个构造函数或 `Clear()` body 中都没有带非零立即数的 `movb $imm`/`movl $imm`；这不同于 `DefaultDebugOptions`（见 [default-debugoptions.md](default-debugoptions.md)），后者写入约 165 个非零立即数。repeated-field 分支从 `@ 0xa2cc520` 加载一个 16 字节 init 常量（`00*8, f0 ff ff ff, 00*4`，共享的 empty-message / `RepeatedField` init），也仍然是纯零。`EmitterLearnedCostModelOptions(Arena*) @ 0x1db63f20` 还将其两个 string 字段指向 `proto2::internal::fixed_address_empty_string`（`= ""`），仍是零默认值。

> **GOTCHA —** 在 `<Msg>_globals_` hexdump 中可见的 `f0 ff ff ff` / `d8 ff ff ff` 字节*不是*字段值。它们是位于字段数据区*之前*的 `MessageLite` 内部 `_cached_size_` / `RepeatedField`-rep / oneof-init 哨兵（对于 `has_bits_offset=16` 的分支，字段数据区从 `+0x18` 开始）。重新实现者若直接从 `_globals_` 读取默认值，必须从 `_table_` 派生的字段偏移开始，绝不能从 `+0x10` 开始。

### 标量 / 混合分支

```text
§ IlpLatencyHidingSchedulerOptions   _table_ 0x21cfa308 · sizeof 0x38 · 6 fields · all default 0/false
  #1 enable_ilp_latency_hiding_scheduler  bool    off=0x30 has=131 tc=0x0011   false
  #2 max_solver_deterministic_time        double  off=0x18 has=128 tc=0x18d3   0.0
  #3 computation_size_threshold           int64   off=0x20 has=129 tc=0x10d1   0
  #4 use_ilp_schedule_sequence            bool    off=0x31 has=132 tc=0x0011   false
  #5 also_minimize_total_lifetime         bool    off=0x32 has=133 tc=0x0011   false
  #6 min_compute_latency                  uint64  off=0x28 has=130 tc=0x08d1   0

§ ShardyOptions                      _table_ 0x21cfa260 · 3 fields · all false
  #1 enable_explicit_collectives           bool  off=0x18 has=128 tc=0x0011   false
  #2 dedup_functions_fully                 bool  off=0x19 has=129 tc=0x0011   false
  #3 enable_native_non_flat_support        bool  off=0x1a has=130 tc=0x0011   false

§ BundleInstrumentationOptions       _table_ 0x21cfa5b0 · 3 fields · all 0/false
  #1 trace_best_effort_frequency           int64 off=0x18 has=128 tc=0x10d1   0
  #2 trace_guaranteed_frequency            int64 off=0x20 has=129 tc=0x10d1   0
  #3 trace_branches                        bool  off=0x28 has=130 tc=0x0011   false

§ BufferContentsSanitizerConfig      _table_ 0x21cf9f58 · 2 fields
  #1 cores_to_sanitize    enum[REPEATED] off=0x18 has=128 tc=0x18a2   [] (empty)
  #2 sanitizer_mode       enum           off=0x2c has=129 tc=0x1891   0 (DEFAULT)
  ENUM CoreToSanitize: INVALID=0, TC=1, SC_SCS=2, SC_TILE=3
  ENUM SanitizerMode: DEFAULT=0, LOCAL_ONLY=1, CROSS_CORE_ONLY=2

Repeated-enum / repeated-primitive 分支

这些分支的单个（或第一个）字段是 repeated enum。默认值是空列表，即未选择任何 feature/op/level；这不是“选择了值 0”，即使每个 enum 的值 0（ALL / FEATURE_UNSPECIFIED / NONE / INVALID）都存在。空列表默认值是 CostModelFlagOptions、SparseCoreOffloadingOptions、AccumulatorTransformations、BufferContentsSanitizerConfig.cores_to_sanitize 以及 RepeatedStrings/RepeatedIntegers 的唯一 AUTO 答案；SparseCoreAssertLevel 是例外，它的消费者会注入非空默认值（§5）。

text

§ CostModelFlagOptions               _table_ 0x21cfa170 · 2 fields · both [] (empty)
  #1 ops_to_use_bundle_aware_cost_model  enum[REP] off=0x18 has=128 tc=0x18a2
  #2 ops_to_use_codegen_windows          enum[REP] off=0x30 has=129 tc=0x18a2
  ENUM OpType: ALL=0, OUTPUT_FUSION=1, CONV_LOWERABLE=2, LOOP_FUSION=3

§ SparseCoreOffloadingOptions        _table_ 0x21cfa110 · 1 field · [] (empty)
  #1 features  enum[REP] off=0x18 has=128 tc=0x18a2
  ENUM OffloadFeature: FEATURE_UNSPECIFIED=0, OP_TRIGONOMETRY=1, OP_SELECT_BF16=2,
    SHAPE_1D_PADDING=3, STANDALONE_OP_DATA_FORMAT=4, FUSION=5, LEM_DATA_FORMAT=6,
    EXPERIMENTAL_FEATURES=7

§ AccumulatorTransformations          _table_ 0x21cf9c30 · 1 field · [] (empty)
  #1 values  enum[REP] off=0x18 has=128 tc=0x18a2  → .xla.jellyfish.AccumulatorTransformation.Value
  ENUM Value: NONE=0, MULTIPLY_ADD_FULLBANDWIDTH=1, MULTIPLY_ADD_HALFBANDWIDTH=2,
    CUMULATIVE_SUM=3, CUMULATIVE_MAX=4, MAX_ABS=5, MULTIPLY_ADD_FULLBANDWIDTH_V2=6

§ SparseCoreAssertLevel               _table_ 0x21cfa550 · 1 field · [] (empty)*  (*see §5)
  #1 values  enum[REP] off=0x18 has=128 tc=0x18a2  → .xla.jellyfish.SparseCoreAssertLevel.Value
  ENUM Value: NONE=0, ALWAYS=1, BOUNDS=2, CSRS=3, CHECKSUMS=4, SYNC_FLAGS=5, STREAMS=6,
    DMA=7, ALL_TO_ALL=8, RADIX_SORT=9, OVERLAYS=10, RUN_IDS=11, VECTOR_LOADS=12,
    VECTOR_STORES=13, SCALAR_LOADS=14, SCALAR_STORES=15, MASKS=16, CONTINUATIONS=17

§ RepeatedStrings   _table_ 0x21cf9d18 · 1 field #1 values string[REP] off=0x18 tc=0x0d25 · [] (empty)
§ RepeatedIntegers  _table_ 0x21cf9da0 · 1 field #1 values int64 [REP] off=0x18 tc=0x10e2 · [] (empty)
```text

> **QUIRK —** 空列表默认值意味着 repeated-enum 分支处于 AUTO 时*什么也不选*，但 enum 的值 `0` 是真实且有意义的第一个值（如果存在，`CostModelFlagOptions.OpType.ALL=0` 表示“所有 ops”）。重新实现若物化单元素 `[0]` 而不是 `[]`，会静默启用二进制保持关闭的功能。默认值是字段不存在，而不是字段的第一个值。

### 最深的树：`EmitterLearnedCostModelOptions`

此分支的描述符位于一个*兄弟* proto 文件中（`emitter_learned_cost_model_options.proto` FDP `@ 0xbfc7bc0`），不在 `tpu_compilation_environment.proto` 中，并为其 #2 子消息拉入 `learned_cost_model_client_options.proto`（FDP `@ 0xbfc8160`）。AUTO learned-cost-model 旋钮是一个 2 层空默认值：9 个外层字段为零，包括一个空的 8 字段 `LearnedCostModelClientOptions`，其自身 enum 也都默认到 `*_UNSPECIFIED=0`。

```text
§ EmitterLearnedCostModelOptions     _table_ 0x21cff9a8 · 9 fields · all default 0/false/""/empty
  #1 enable_learned_cost_model           bool    off=0x38 has=132 tc=0x0011   false
  #2 learned_cost_model_client_options   message off=0x28 has=130 tc=0x0416   absent
                                         → .xla.jellyfish.LearnedCostModelClientOptions
  #3 max_num_considered_windows          int64   off=0x30 has=131 tc=0x10d1   0
  #4 dump_fusion_data_proto              bool    off=0x39 has=133 tc=0x0011   false
  #5 db_path                             string  off=0x18 has=128 tc=0x0c15   "" (empty)
  #6 db_query_type                       enum    off=0x3c has=134 tc=0x1891   0 (DB_QUERY_TYPE_NONE)
  #7 cost_model_mode                     enum    off=0x40 has=135 tc=0x1891   0 (..._MODE_INVALID)
  #8 ml_output_validation_strategy       enum    off=0x44 has=136 tc=0x1891   0 (..._STRATEGY_NONE)
  #9 dump_fusion_data_proto_dir          string  off=0x20 has=129 tc=0x0c15   "" (empty)
  ENUM LearnedCostModelMode: ..._INVALID=0, ..._ONLY_ML_PREDICTION=1, ..._ONLY_DB=2,
    ..._DB_WITH_FALLBACK_TO_ML_PREDICTION=3, ..._ONLY_DATA_COLLECTION=4
  ENUM DbQueryType: DB_QUERY_TYPE_NONE=0, DB_QUERY_TYPE_REPLAY_PREDICITIONS=1, DB_QUERY_TYPE_GROUND_TRUTH=2
  ENUM MLOutputValidationStrategy: ..._NONE=0, ..._NEVER_TRUST=1, ..._ALWAYS_TRUST=2, ..._NO_NEGATIVE_CYCLES=3

  SUB-MESSAGE LearnedCostModelClientOptions (FDP @0xbfc8160; 8 fields; all empty/0):
    #1 embedding_service_type                  enum (ServiceType)
    #2 remote_embedding_server_address         string
    #3 remote_embedding_model_name             string
    #4 inflight_rpc_monitoring_interval_milliseconds  int32
    #5 local_embedding_model_path              string
    #6 embedding_cache_path                    string
    #7 fusion_data_proto_generation_options     message (FusionDataProtoGenerationOptions: 2 bools)
    #8 max_batch_size                          int32
    ENUM ServiceType: SERVICE_TYPE_UNSPECIFIED=0, SERVICE_TYPE_LOCAL=1, SERVICE_TYPE_REMOTE=2

这里解码了 enum 值集合（驱动 learned cost model 的结构化旋钮）；它们从 cost-model 文档交叉链接而来。值得标记的两个 enum 默认语义：cost_model_mode=0 是 LEARNED_COST_MODEL_MODE_INVALID（显式无效，不是良性默认值），并且该字段只有在 enable_learned_cost_model 为 true 后才有意义；默认并不是 true。

3. `TpuCustomCallMemorySpaceSpec` Oneof

目的

TpuCustomCallMemorySpaceSpec 是唯一带内部 oneof 的消息分支。它的两个消息字段 msa_reservation_policy 和 hbm_policy 是名为 policy 的同一个 oneof 的成员，因此二者互斥：恰好一个（或都不）被设置。这是 AutoProto-oneof 机制（off 0x10，case at +0x1c，oneof bit 0x20）递归到下一层：一个基于同一套 TcParser 机制、与 30 分支 AutoProto oneof 自身相同的微型 2 分支 oneof。

布局

text

TpuCustomCallMemorySpaceSpec object   (sizeof 0x20)
  +0x00  vtable ptr (→ vtable+0x10 @0x21cf9740)
  +0x08  Arena / InternalMetadata tagged ptr
  +0x10  oneof union (8 B): MsaReservationPolicy* | HbmPolicy*  (whichever arm is active)
  +0x18  unused has-bits word (ctor zeros it)
  +0x1c  oneof _case_ : 0 = unset, 1 = msa_reservation_policy, 2 = hbm_policy
```text

```text
TpuCustomCallMemorySpaceSpec::_table_ @ 0x21cfa708
  has_bits_offset=0x18, max_field=2, num_aux=2, aux@table+0x68
  field#1 msa_reservation_policy  off=0x10  case_off=0x1c  aux=0  tc=0x0436 (oneof-msg)
            → aux[0] MsaReservationPolicy::_table_ @ 0x21cfa658
  field#2 hbm_policy              off=0x10  case_off=0x1c  aux=1  tc=0x0436 (oneof-msg)
            → aux[1] HbmPolicy::_table_ @ 0x21cfa6b8

Nested MsaReservationPolicy  _table_ @ 0x21cfa658  (_globals_ @ 0x223c8538)
  #1 msa_reservation_size_bytes  uint64  off=0x18  tc=0x08d1   default 0
Nested HbmPolicy             _table_ @ 0x21cfa6b8  (_globals_ @ 0x223c8558)  0 fields — marker message

三个字节来源确认 oneof

两个字段都位于 struct off 0x10（单个 8 字节 union 指针），has_idx=0x1c（oneof _case_ word offset，不是 has-bit；has-bit 会是 128+），并且 type_card=0x0436（singular-message 0x0416 加上 TcParser oneof 位 0x20）。0x0436 值与 AutoProto 主 oneof 交叉确认：其每个分支都使用 oneof family（bool 0x0031、int64 0x10f1、string 0x0c35、message 0x0436，均为 = singular | 0x20）。

生成的方法证明单分支语义：每个方法都按 +0x1c 的 case word switch，并且只触碰一个分支：

function clear_policy(this):                 // 0x1db25f00
    switch this->_case_ {                     // mov 0x1c(%rdi),%eax
      case 2: ~HbmPolicy; free(0x18 bytes)
      case 1: ~MsaReservationPolicy; free(0x20 bytes)
    }
    this->_case_ = 0                          // movl $0,0x1c

function _InternalSerialize(this, ...):      // 0x1db263c0
    switch this->_case_ {                     // mov 0x1c,%edi
      case 1: WriteMessage(field 1, msa @ rep+0x14)
      case 2: WriteMessage(field 2, hbm @ rep+0x10)
    }                                         // exactly one message field emitted, never both
```text

`Clear() @ 0x1db26300` 和 `ByteSizeLong() @ 0x1db26420` 复现了同样的 case switch；ctor `@ 0x1db25fa0` 执行 `movq $0,0x18(%rdi)`（清零未使用 has-bits word 和 case discriminator → case 0 = unset）。雕刻出的 FDP（`@ 0xbfa6060`）在 schema 层面确认了 oneof：`oneof_decl[0].name="policy"`；两个字段都携带 `oneof_index=0`。`.rodata` 字符串 `"policy"`、`"msa_reservation_policy"`、`"hbm_policy"`、`"msa_reservation_size_bytes"` 也相互印证。

> **QUIRK —** 共享的 `off=0x10`/`case=0x1c` 指纹与 `AutoProto` oneof 自身布局完全一致（见 [autoproto-autoor-resolution.md](autoproto-autoor-resolution.md)）。若重新实现者把 `msa_reservation_policy` 和 `hbm_policy` 当作两个独立 `optional` 子消息（都可能存在），就会错误估算结构体大小（两个指针而不是一个 union word），并错误序列化（两个字段，而二进制只发出一个）。它是一个 oneof，不是两个 optionals。

---

## 4. `text:` 形式的消息分支 SET 路径

### 目的

消息分支的默认值为空（§2）。本节是*写入*方向：JAX flag 值（`--<flag>=text:<field>: <VAL>` 及类似形式）如何把该空默认实例变成填充后的 config。路径是带 libtpu 特定入口（`AbslParseFlagImpl`）和三种按分支区分的 `ParseFlag` 风格的通用 protobuf 反射摄入。

### 入口点

```text
AutoOr<Msg>::ParseFlag(value)                       ── per-arm, e.g. 0x1d747b00 (Ilp), 0x1d744f80 (CostModel)
  ├─ bcmp value vs "auto" → AUTO (empty default, present byte clear)
  └─ else construct Msg(arena) and run the arm's MESSAGE PARSER:
       Message::AbslParseFlagImpl @ 0x20ef2120       ── generic: Clear(), then format dispatch
         ├─ "text:"       → TextFormat::Parser::ParseFromString @ 0x20efd420
         │                    └─ ConsumeField @ 0x20f037e0 → ConsumeFieldValue @ 0x20f07a60
         │                         └─ is_repeated? Reflection::Add* : Reflection::Set*
         ├─ "serialized:"  → MessageLite::ParseFromString @ 0x21057460
         └─ "base64:"      → Base64Unescape @ 0x2116df80 then ParseFromString

flag 值解析（`AbslParseFlagImpl`）

proto2::Message::AbslParseFlagImpl @ 0x20ef2120 是通用 message-flag parser。它先（通过 vtable *0x10）Clear() 消息，然后根据格式前缀分派：

function Message::AbslParseFlagImpl(this, value, &error):   // 0x20ef2120
    (*this->vtable[0x10])(this)                  // Clear() — start from the empty default
    if value[0] == ':': delimited = 1            // leading ':' = delimited-format specifier
    memchr(value, ':')                           // locate the format prefix
    split format-options on ',' (ByChar Splitter @ 0xe6d1240)
    switch prefix:                               // in-body immediates: "text"=0x74786574, "serialized", "base64"
      "text"       → TextFormat::Parser ctor @ 0x20efde40; ParseFromString @ 0x20efd420
      "serialized" → MessageLite::ParseFromString @ 0x21057460
      "base64"     → Base64Unescape @ 0x2116df80; then ParseFromString
      default      → text                         // no prefix = text
    // field-name collision: "Prefix `%s:` ... ambiguous with message fields" (Descriptor::FindFieldByName @ 0x20e57900)
    //                       "Invalid format `%s`."
```text

反编译确认了每个分支：`ParseFromString` serialized 路径、`"Invalid base64 input."` 错误、`TextFormat::Parser` ctor + `ParseFromString`，以及 ambiguous-prefix 错误字符串（`"Prefix \`%s:\` used is ambiguous with message fields. ... use \`:text:\` as a prefix."`）。默认（无前缀）是 text。

### `text:` 值如何变成字段（`Add*` 与 `Set*` 分流）

在 TextFormat parser 内部，每个 consumed value 的 repeated-vs-singular 决策是 `proto2::FieldDescriptor::is_repeated`，编码为 `FieldDescriptor+0x1` 的 bit `0x20`。`ConsumeFieldValue @ 0x20f07a60` 的反编译原样显示了这个测试：`(*((_BYTE *)FieldDescriptor + 1) & 0x20) != 0` 按 CPP type 选择 `Add*` 分支而非 `Set*` 分支：

```c
function ConsumeFieldValue(this, msg, reflection, field):   // 0x20f07a60
    // ... parse one value of the field's CPP type ...
    if (field[1] & 0x20) != 0:                  // FieldDescriptor::is_repeated
        Reflection::Add<T>(reflection, msg, field, value)   // APPEND to RepeatedField at arm +0x18
    else:
        Reflection::Set<T>(reflection, msg, field, value)   // overwrite the singular slot

解码出的 Add* / Set* 系列：

CPP type	Repeated →	Singular →
double	`AddDouble`	`SetDouble`
float	`AddFloat`	`SetFloat`
int32	`AddInt32 @ 0x20ecf940`	`SetInt32`
int64	`AddInt64 @ 0x20ed03c0`	`SetInt64`
bool	`AddBool @ 0x20ed3900`	`SetBool`
string	`AddString`	`SetString`
enum	`AddEnum @ 0x20ed8860`（在 `FindValueByName`/`AddEnumValue` 之后）	`SetEnum @ 0x20ed8480`

对 enum 元素，parser 执行 ConsumeIdentifier → EnumDescriptor::FindValueByName；数字 token 走 ConsumeSignedInteger → FindValueByNumber，没有匹配 descriptor entry 的数字只有在 !FieldDescriptor::legacy_enum_field_treated_as_closed 时才会通过 AddEnumValue @ 0x20f06... 接纳（closed-enum guard）。每个 Add* 都向位于分支结构体 +0x18 的 RepeatedField 追加一个元素；这是 §2 为全部五个 repeated 分支记录的偏移。因此，--xla_tpu_sparse_core_offloading_options=text:features: FUSION features: LEM_DATA_FORMAT 会把 AUTO-empty SparseCoreOffloadingOptions 变成 2 元素集合。

支持 repeated 短列表 field: [A, B, C]：ConsumeField @ 0x20f037e0 有 cmpb $0x5b（'['）开括号路径，会在逗号分隔列表上循环调用 ConsumeFieldValue，同时也支持逐次出现的 field: A field: B 形式。二者都会逐元素追加；这是标准 proto TextFormat repeated grammar，不是 TPU 自定义语法。

GOTCHA — repeated 分支中未知 enum 名称的 closed-enum 容忍度尚未按字节追踪到错误字符串（legacy_enum_field_treated_as_closed 分支存在，但 error-vs-silent-skip 行为未确认，LOW）。重新实现者不应假设拼错的 features: 名称一定被拒绝；它可能落入 UnknownFieldSet。

三种按分支区分的摄入风格

分支的 AutoOr<Msg>::ParseFlag 决定用户书写哪种语法。从每个分支的 callee set 解码出三种风格：

风格	分支（`ParseFlag` VA）	语法
A — 纯 TextFormat（仅 `AbslParseFlagImpl`）	`CostModelFlagOptions` (`0x1d744f80`), `SparseCoreOffloadingOptions` (`0x1d745d80`), `IlpLatencyHidingSchedulerOptions` (`0x1d747b00`), `ShardyOptions` (`0x1d746e20`), `EmitterLearnedCostModelOptions` (`0x1d745680`), `BundleInstrumentationOptions` (`0x1d749ce0`), `TpuCustomCallMemorySpaceSpec` (`0x1d74a3c0`)	`--<flag>=text:<field>: <VAL>`（或 `serialized:`/`base64:`）
B — 自定义逗号列表（`AutoOrTypeTraits<T>::Parse`，加 TextFormat fallback）	`RepeatedStrings`（Parse `0x1d746720`：`ByChar::Find` split → 每个 token 执行 `RepeatedPtrFieldBase::Add<string>`）、`RepeatedIntegers`（Parse `0x1d7446e0`：split → `safe_strto64_base @ 0x21173e20` → append int64）、`AccumulatorTransformations`（Parse `0x1d748f40`：split → `ParseNamedEnum` → append enum）	`--<flag>=A,B,C` 或 `text:values: A`
C — preset / level 逗号列表（`assert_level::Parse @ 0x1db1e3e0`）	`SparseCoreAssertLevel`（`ParseFlag 0x1d7495e0`）：`ByChar(',')` split，每个 token 经 `StringToAssertLevel @ 0x1db1e8a0`（preset aliases）或 `StringToEnum @ 0x1db1ec60`（单个 level 名称）	`--xla_sc_assert_level=prod`（preset）或 `=bounds,csrs,checksums`（level list）

风格 B 分支也都保留 AbslParseFlagImpl 作为 fallback，因此同时接受逗号列表短形式和完整 text: 形式。

NOTE — EmitterLearnedCostModelOptions 的嵌套子消息摄入（2 层 text:learned_cost_model_client_options { embedding_service_type: SERVICE_TYPE_REMOTE … } 块）未单独按字节走查；它使用同一个通用 AbslParseFlagImpl → ConsumeFieldMessage 递归（INFERRED-by-pattern — HIGH）。serialized:/base64: repeated-element wire encoding（packed vs unpacked）同样未追踪（LOW）；只有 text: append 路径按字节确认。

5. 消费者侧 `AUTO` 覆盖

目的

§2 证明每个消息分支的 proto 默认值为空。两个分支在空 proto 之上有代码侧默认值：consumer accessor 先物化空实例，然后在 AutoOr 为 AUTO/absent 时无条件替换为非空值。对这两个分支而言，实际发布默认值不是 proto-empty 值；重新实现若停在 proto 层会得到错误行为。

`assert_level::prod()`：`SparseCoreAssertLevel` 默认值

GetSparseCoreAssertLevel @ 0x1d6b9ac0（env+0xb78 = 2936）读取 AutoProto*，null 时回退到 AutoProto_globals_ @ 0x223c8968（case 0 ⇒ AUTO），解析 AutoOr<SparseCoreAssertLevel>::FromProtoOrDie，然后无条件调用 assert_level::prod()，并在 AutoOr 为 AUTO/absent 时使用它：

function GetSparseCoreAssertLevel(out, env):                // 0x1d6b9ac0
    p = env[+0xb78]                                          // AutoProto* (xla_sc_assert_level)
    if !p: p = &AutoProto_globals_                           // 0x223c8968 — AUTO
    AutoOr<SparseCoreAssertLevel>::FromProtoOrDie(autoor, p) // stack AutoOr
    chosen = assert_level::prod()                            // 0x1db1d8a0 — UNCONDITIONAL
    if autoor.present == 1:                                  // user supplied a value
        chosen = autoor.value
    SparseCoreAssertLevel(out, arena=0, chosen)             // copy chosen into the sret
```text

`prod() @ 0x1db1d8a0` 先构建空的 `SparseCoreAssertLevel(arena=0)`，然后通过 `RepeatedField<int>::GrowNoAnnotate` + store 向 repeated `values` 字段恰好追加一个值 `1`（= `Value.ALWAYS`）。反编译确认了单次 `RepeatedField<int>` append 和 `*((_BYTE*)this+16) |= 1u` presence set。因此，**未设置 `xla_sc_assert_level` 的实际发布默认值是 `{values:[ALWAYS]}`**，即廉价的 always-on bounds/safety asserts，而不是 §2 的空 proto。

`prod()` 所属的 preset family（为对比而解码；每个都是 `SparseCoreAssertLevel(arena=0)` + 固定 appended-value list，数字对应 §2 的 `Value` enum）：

```text
prod()                = [1]                  (ALWAYS)                       CLI keyword "prod"
san_lite()            = [5,6,7,8,11]          (SYNC_FLAGS,STREAMS,DMA,ALL_TO_ALL,RUN_IDS)   "san-lite"
vector_loads_stores() = [12,13]               (VECTOR_LOADS,VECTOR_STORES)  "vector-loads-stores"
all_loads_stores()    = [12,13,14,15]         (VECTOR/SCALAR LOADS+STORES)  "all-loads-stores"
san()                 = [1..15,17]            (ALWAYS..SCALAR_STORES + CONTINUATIONS; skips 16=MASKS)   "san"

QUIRK — SparseCoreAssertLevel 是唯一带代码 fallback 的 repeated 分支。EnableAnyAccumulatorTransformation @ 0x1d6b98e0 / EnableAccumulatorTransformation @ 0x1d6b9660 解析空的 AccumulatorTransformations 默认值，并直接对其做 membership-test，没有注入默认值；因此对 AccumulatorTransformations，实际默认值仍然是 proto-empty list。不要把 prod() 覆盖泛化到 repeated 分支；它只适用于一个分支。（CostModelFlagOptions/SparseCoreOffloadingOptions 的 consumer 是否在空 proto 后注入代码默认值尚未穷尽扫过，LOW。）

`ResolveMemorySpaceSpec`：`TpuCustomCallMemorySpaceSpec` 默认值

custom-call memory-space spec 有自己的消费者侧 AUTO 默认值。TpuCustomCallMemorySpacePolicy::ResolveMemorySpaceSpec @ 0x11036320 在 AUTO（AutoOr 分支不存在）时执行 clear_policy()，然后 Arena::DefaultConstruct<MsaReservationPolicy>，并从 Target::VmemSizeBytes @ 0x1d615e00 / scoped_memory_util::DefaultScopedVmemBytes @ 0x1c864e40 填充 msa_reservation_size_bytes：

function ResolveMemorySpaceSpec(target, module, autoor):    // 0x11036320
    if autoor is AUTO (not present):
        spec.clear_policy()                                  // 0x1db25f00
        msa = Arena::DefaultConstruct<MsaReservationPolicy>(arena)
        msa.msa_reservation_size_bytes =
            scoped_memory_util::DefaultScopedVmemBytes(target, module, Target::VmemSizeBytes(target))
    else:
        switch autoor.value.policy_case { 1: MSA; 2: HBM }   // dispatch the user oneof arm
```text

因此 AUTO policy 是一个定大小到默认 scoped VMEM 的 MSA reservation：空 proto，代码物化 policy。反编译确认 AUTO 分支中出现 `clear_policy`、`DefaultConstruct<...MsaReservationPolicy>`、`Target::VmemSizeBytes` 和 `DefaultScopedVmemBytes`。`ResolveMemorySpaceSpec` 是否是*唯一* spec consumer 尚未确认（LOW）。

---

## 相关组件

| 组件 | 关系 |
|---|---|
| `AutoProto::_table_ @ 0x21cfa788` | 父级 30 分支 oneof；12 个消息分支是其 `0x04xx` `type_card` members |
| `AutoProto_globals_ @ 0x223c8968` | 消息分支 getter 回退到的 all-AUTO 默认实例（case 0） |
| `Message::AbslParseFlagImpl @ 0x20ef2120` | 通用 message-flag parser：`text:`/`serialized:`/`base64:` 分派 |
| `TextFormat::Parser::ParseFromString @ 0x20efd420` · `ConsumeFieldValue @ 0x20f07a60` | `text:` 摄入；`is_repeated` 位 `0x20` → `Add*`/`Set*` 分流 |
| `assert_level::prod() @ 0x1db1d8a0` · `GetSparseCoreAssertLevel @ 0x1d6b9ac0` | `xla_sc_assert_level` 的 `{values:[ALWAYS]}` 消费者默认值 |
| `ResolveMemorySpaceSpec @ 0x11036320` | `TpuCustomCallMemorySpaceSpec` 的定大小到 VMEM 的 MSA 消费者默认值 |
| `tpu_compilation_environment.proto` FDP `@ 0xbfa6060` | 命名 12 个分支中的 11 个以及 `policy` oneof 的雕刻描述符 |

## 交叉引用

- [autoproto-autoor-resolution.md](autoproto-autoor-resolution.md)：解析模型；负责*标量* `AutoOr<T>` 分支（本页负责*消息类型*分支及其 Idiom-E 默认值）
- [autoor-parse-grammar.md](autoor-parse-grammar.md)：消息分支 `text:` 摄入旁边的标量 `auto`/`enabled`/`disabled`/literal token 语法
- [autoor-unparse.md](autoor-unparse.md)：反向的 `AbslUnparseFlag<AutoOr<T>>` text 方向
- [tpu-compilation-environment.md](tpu-compilation-environment.md)：承载这些分支所支持 `AutoProto*` 字段的 TCE proto，以及 field#→offset oracle
- [tce-field-offsets-defaults.md](tce-field-offsets-defaults.md)：字节精确的 field#→offset→default map；此处按 consumer 引用的 env offsets
- [registry-mediated-flags.md](registry-mediated-flags.md)：将每个消息分支 flag 名称绑定到其 TCE 字段的 flag registry
- [default-debugoptions.md](default-debugoptions.md)：对照项：一个默认实例*带有*约 165 个非零默认写入器，不同于此处的全零消息分支
- [overview.md](overview.md)：AutoProto 旋钮所在的三层 config pipeline

AutoProto 消息分支 ​

摘要 ​

1. 消息分支清单 ​

目的 ​

共享的 _table_ 布局 ​

清单 ​

2. 每个分支的字段字典和空默认值 ​

目的 ​

全零默认值证明 ​

Repeated-enum / repeated-primitive 分支 ​

3. TpuCustomCallMemorySpaceSpec Oneof ​

目的 ​

布局 ​

三个字节来源确认 oneof ​

flag 值解析（AbslParseFlagImpl） ​

三种按分支区分的摄入风格 ​

5. 消费者侧 AUTO 覆盖 ​

目的 ​

assert_level::prod()：SparseCoreAssertLevel 默认值 ​

ResolveMemorySpaceSpec：TpuCustomCallMemorySpaceSpec 默认值 ​

AutoProto 消息分支

摘要

1. 消息分支清单

目的

共享的 `_table_` 布局

清单

2. 每个分支的字段字典和空默认值

目的

全零默认值证明

Repeated-enum / repeated-primitive 分支

3. `TpuCustomCallMemorySpaceSpec` Oneof

目的

布局

三个字节来源确认 oneof

flag 值解析（`AbslParseFlagImpl`）

三种按分支区分的摄入风格

5. 消费者侧 `AUTO` 覆盖

目的

`assert_level::prod()`：`SparseCoreAssertLevel` 默认值

`ResolveMemorySpaceSpec`：`TpuCustomCallMemorySpaceSpec` 默认值