nscn.polaris2.protoc.runtime

Bridges a generated Scala message to protobuf-java's DynamicMessage.

The point is leverage rather than convenience. Text format, and later JSON, have long specifications full of special cases - Well-Known Type shorthands, enum naming, field ordering - and protobuf-java already implements all of it against Message. Converting once and delegating is both far less code than a second implementation and far more likely to agree with every other protobuf library.

The conversion leans entirely on GeneratedMessage.getFieldByNumber returning base values, so nothing here has to know that a field's Scala type may be a mapped one.

Base trait of every generated proto enum.

Generated as a Scala 3 enum whose cases carry their proto number, plus an Unrecognized case:

enum Color(val value: Int) extends GeneratedEnum derives CanEqual:
 case COLOR_UNKNOWN extends Color(0)
 case COLOR_RED     extends Color(1)
 case Unrecognized(unrecognizedValue: Int) extends Color(unrecognizedValue)

Unrecognized is present even on a closed enum, so the API does not change shape with the enum's openness. Parsing a closed enum never produces it - an out-of-range value there belongs in the unknown fields, which is what editions mandates - so it can only come from an explicit GeneratedEnumCompanion.fromValue call.

The file-level object a generated file declares: its descriptor plus the companions of everything in it.

Exists so a consumer can reach the descriptors of a whole file without naming each message, which is what a registry or a reflection service needs.

Base trait of every generated message.

Serialization is the generated code's own specialized loop over protobuf-java's CodedOutputStream; this trait only adds the conveniences that do not depend on the message's shape. Reflective access goes through getFieldByNumber, which returns base values - the proto-level type, with any TypeMapper already undone - so the generic machinery in DynamicMessages never has to know about custom types.

Base trait of every generated message's companion object: how to parse one, and the descriptors describing it.

Base trait of the nested enum generated for a proto oneof.

enum Contact extends GeneratedOneof derives CanEqual:
 case Empty
 case Email(value: String)
 case Phone(value: String)

The accessors are named oneofNumber / oneofValue rather than the obvious number / value so they cannot collide with the value parameter each case already carries.

The Scala shape of google.protobuf.Any: a type URL and the bytes it describes.

Kept as its own type rather than mapped to a stdlib one, because there is no stdlib type for "some message, identified at runtime". pack and unpackTo are where the type recovery happens, and they need the target's companion, which is exactly what a generated companion provides.

The Scala shape of google.protobuf.Value: a JSON-like tree.

Struct, Value and ListValue exist in protobuf to carry dynamically typed data, so surfacing them as generated messages produces exactly the code a caller does not want to write. This ADT is what those three map to by default.

A bijection between a proto type and the Scala type a field should actually have.

This is the single extension point behind both user-declared (nscn.polaris2.protoc.field).type options and the built-in Well-Known Type mapping: the generated field has type Custom, while the wire format and reflective access stay in terms of Base.

toBase(toCustom(b)) == b is expected to hold. Where it cannot - java.time.Instant normalizes, so a Timestamp with nanos >= 1e9 does not come back unchanged - the mapping is documented and can be turned off per field.

The default mapping from Well-Known Types to Scala and Java standard library types.

The raw side of every mapping is protobuf-java's own generated class rather than a hand-written Scala mirror. That is what (nscn.polaris2.protoc.field).wkt_mapping = RAW falls back to, and it means there is no second implementation of Timestamp to keep in step with protobuf's.

The generator emits references to these mappers by name, so they are plain vals and not only givens - nothing here depends on implicit search succeeding.

The few wire-format operations that are identical in every generated message.

Deliberately small. Per-field encoding stays inlined in the generated code, where the field number and type are constants the JIT can see; what is factored out here is only the length-prefix bookkeeping, which is verbose, easy to get subtly wrong, and the same every time.