table: use the table for messages with a oneof

.changes/unreleased/added-20260923-codec-strategy-table.yaml

@@ -1,4 +1,4 @@
 kind: Added
 body: |-
-    **Table-driven message codec** (#469, refs #463). `buffa_build::Config::codec_strategy(CodecStrategy::Table)` (plugin option `codec_strategy=table`, `CodeGenConfig::codec_strategy`) generates each message's binary `Message` implementation from a static table and interpreters that every message shares, instead of code specialised to the message's fields. The compiled code is substantially smaller, and messages made of many small fields are slower. `CodecStrategy::Unrolled` stays the default. `codec_strategy_in(strategy, &[paths])` (plugin option `codec_strategy_in=<path>=<strategy>`, repeatable) chooses the strategy for matching messages and the messages nested in them, and the last matching rule wins. The wire format does not change. Messages the table cannot handle stay unrolled, and `CodeGenWarning::TableCodecFallbackSummary` counts them. A rule that selects the table, by exact path, for a message that cannot use it is an error. The generated code needs Rust 1.77 or later, which `buffa-build` checks, and compiles in a crate with `#![forbid(unsafe_code)]`. The guide's "Smaller generated code" section has the measurements, the messages that stay unrolled and the behavioural differences.
+    **Table-driven message codec** (#469, refs #463). `buffa_build::Config::codec_strategy(CodecStrategy::Table)` (plugin option `codec_strategy=table`, `CodeGenConfig::codec_strategy`) generates each message's binary `Message` implementation from a static table and interpreters that every message shares, instead of code specialised to the message's fields. The compiled code is substantially smaller, and messages made of many small fields are slower. `CodecStrategy::Unrolled` stays the default. `codec_strategy_in(strategy, &[paths])` (plugin option `codec_strategy_in=<path>=<strategy>`, repeatable) chooses the strategy for matching messages and the messages nested in them, and the last matching rule wins. The wire format does not change, and a message with a `oneof` uses the table, including when a member is a message that has no table. Messages the table cannot handle stay unrolled, and `CodeGenWarning::TableCodecFallbackSummary` counts them. A rule that selects the table, by exact path, for a message that cannot use it is an error. The generated code needs Rust 1.77 or later, which `buffa-build` checks, and compiles in a crate with `#![forbid(unsafe_code)]`. The guide's "Smaller generated code" section has the measurements, the messages that stay unrolled and the behavioural differences.
 time: 2026-09-23T03:10:00+00:00

.github/workflows/ci.yml

@@ -305,7 +305,10 @@ jobs:
       # provenance, alignment and initialisation on the kinds and field
       # shapes the module's tests build, including message fields stored
       # inline, boxed and in a `Vec`, whose child pointers point into the
-      # parent or the heap.
+      # parent or the heap, and oneofs, through hand-written enums with
+      # inline and boxed message members. The `OneofEnum` code that codegen
+      # emits runs natively only, in the differential tests of `buffa-test`,
+      # not under Miri.
       - name: Miri (table interpreter soundness)
         run: cargo +${{ env.MIRI_TOOLCHAIN }} miri test -p buffa --lib -- 'table::'
 

DESIGN.md

@@ -560,12 +560,13 @@ Within that bound, the shortcuts do not pay off. `merge` does not help: it consu
 
 The size, write, and merge code of an unrolled message is specialised to its fields. `CodecStrategy::Table` (a per-message option, `Unrolled` by default) replaces it with a static `buffa::table::Table<M>` and a `Message` impl that forwards to interpreters in `buffa::table`. The decision to keep `Unrolled` as the default is in [#463](https://github.com/anthropics/buffa/issues/463), and the guide's "Smaller generated code" section has the measurements and the list of messages that stay unrolled.
 
-A table holds a sorted array of 12-byte entries `{tag, offset, kind, tag_len, aux}`, a dense array that maps field numbers below 64 to entries, and the offset of the unknown-fields slot. `kind` is the field type crossed with its cardinality, so the interpreter dispatches once per field. Message, repeated-message, and enum fields carry a small descriptor (`Aux`) with the accessors that their storage needs, because a `MessageField`, a `Vec`, and an `EnumValue` cannot be read through an offset alone. Offsets come from `core::mem::offset_of!`, so the table needs Rust 1.77 and the generated code refers to it through `buffa::__table!`, which is a compile error on an older compiler.
+A table holds a sorted array of 12-byte entries `{tag, offset, kind, tag_len, aux}`, a dense array that maps field numbers below 64 to entries, and the offset of the unknown-fields slot. `kind` is the field type crossed with its cardinality, so the interpreter dispatches once per field. Message, repeated-message, and enum fields carry a small descriptor (`Aux`) with the accessors that their storage needs, because a `MessageField`, a `Vec`, and an `EnumValue` cannot be read through an offset alone; a oneof has a `Group` descriptor and each of its members a `Member` one. Offsets come from `core::mem::offset_of!`, so the table needs Rust 1.77 and the generated code refers to it through `buffa::__table!`, which is a compile error on an older compiler.
 
-Three decisions shape the runtime:
+Four decisions shape the runtime:
 
 - **The `unsafe` lives in `buffa`.** `__table!` and `__table_entry!` contain the `unsafe` blocks and witness each field's type against its kind, so a table that names the wrong kind for a field does not compile, and generated code compiles under `#![forbid(unsafe_code)]`. `Table::new` also checks the layout constants at compile time. The interpreters run under Miri in CI.
 - **The interpreters are not generic over the sink or the input where that is avoidable.** `Message::encode` and its siblings write any `BufMut` through one shared, non-generic cursor (`buffa/src/encode_sink.rs`), and decoding runs over a contiguous `&[u8]`, so the interpreters are compiled once in `buffa`, at its `opt-level`, and not once per caller.
+- **A oneof is one table entry per member,** all at the offset of the `Option<Enum>`, because that enum has no specified layout. Generated code implements the safe trait `OneofEnum` for it, so the interpreters can find the member that is set, and the `unsafe` stays in `buffa`. The bytes and the decoding are the same as unrolled code's; the documentation of `OneofEnum` in `buffa/src/table/oneof.rs` describes the mechanism and what an implementation must guarantee.
 - **A child reaches the interpreters through its table or its `Message` impl.** A message field's `Aux` descriptor holds either the child's `MessageTable` or a `DynVt` of function pointers instantiated for the child type (`table/bridge.rs`), so a table message can hold any message it is not required to leave unrolled. The write pointer takes the `PreSized` cursor because a function pointer cannot be generic over the sink. A pointer per child type and sink type would avoid the copy that other sinks cost, at the price of code in every crate that uses the table. The planner in `buffa-codegen` (`table_plan.rs`) selects the messages that asked for the table and drops those the interpreters cannot handle. Among them it drops, transitively, the holders of a message of the run with a non-default bytes type, because the table decodes from one contiguous slice and would copy the `bytes::Bytes` fields that unrolled code shares with a `Bytes` input. A child from another crate is not inspected, so a holder of `google.protobuf.Any`, whose `value` is `bytes::Bytes`, keeps its table and copies the payload.
 
 ### Owned decode: intentional throughput trade-offs

buffa-codegen/src/lib.rs

@@ -1094,7 +1094,7 @@ pub enum CodecStrategy {
     ///
     /// Not every message can use it. These stay [`Unrolled`](Self::Unrolled):
     ///
-    /// - a message with a `oneof`, a `map` field, or a group field;
+    /// - a message with a `map` field or a group field;
     /// - the message type of a group field;
     /// - a message that uses the `MessageSet` wire format;
     /// - a message with extension ranges, when JSON code is generated and
@@ -1108,9 +1108,10 @@ pub enum CodecStrategy {
     ///   contiguous slice, so it would copy `bytes::Bytes` fields that
     ///   unrolled code decoding from a `Bytes` shares with the input.
     ///
-    /// A table message may hold any other message. It reaches a child that is a
-    /// table message through the child's table, and any other child, whether
-    /// it is [`Unrolled`](Self::Unrolled), generated by another crate, or a
+    /// A table message may hold any other message, including as a member of a
+    /// `oneof`. It reaches a child that is a table message through the
+    /// child's table, and any other child, whether it is
+    /// [`Unrolled`](Self::Unrolled), generated by another crate, or a
     /// well-known type, through the child's `Message` impl, which costs a
     /// function call per child. Selecting a message does not select the
     /// messages it holds, and keeping a child [`Unrolled`](Self::Unrolled) does
@@ -1156,7 +1157,7 @@ pub enum CodecStrategy {
 #[derive(Debug, Clone, PartialEq, Eq)]
 #[non_exhaustive]
 pub struct TableCodecFallbackReason {
-    /// The reason as a predicate, such as `has a oneof`. The wording is for
+    /// The reason as a predicate, such as `has a map field`. The wording is for
     /// people and may change between releases.
     pub reason: String,
     /// The proto paths of all of them, with a leading dot, in declaration