feat: reject hand-set deprecated in the field_metadata annotation

The `deprecated` attribute is generator-managed — mirrored from the field's
standard `[deprecated = true]` option. A hand-set value inside
(meshtastic.field_metadata) previously produced silently divergent output:
the Go and Kotlin/Wire generators emitted it while the Swift plugin ignored
it (breaking byte-identity), and the schema carried two sources of truth for
the same fact.

Make it a hard error at generation time in all three generators, with the
same message naming the field and the fix. Verified: both protoc plugins
reject a hand-set fixture identically; parity over the real schema remains
byte-identical; Go tests cover true/false/redundant hand-set cases.

Also document the Go plugin's `target=swift` assumption that files set
`option swift_prefix = ""` (all meshtastic protos do) — without it,
swift-protobuf prefixes generated type names and the emitted extensions
would reference nonexistent types; the parity CI catches that divergence.

The bundled field_metadata.pb.swift regen picks up the proto comment change
(comments only, no functional difference).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: jamesarich

meshtastic/field_metadata.proto

@@ -69,9 +69,10 @@ message FieldMetadata {
    * Field is deprecated. MIRRORS the field's standard `[deprecated = true]`
    * option — the generators populate this automatically from that option so
    * every consumer can read it at runtime (protobuf runtimes strip options, so
-   * the standard `deprecated` bit is otherwise invisible to apps). Do NOT set
-   * this by hand in a (meshtastic.field_metadata) annotation; mark the field
-   * `[deprecated = true]` as usual and it flows through here.
+   * the standard `deprecated` bit is otherwise invisible to apps). Setting it
+   * by hand in a (meshtastic.field_metadata) annotation is a generation-time
+   * ERROR; mark the field `[deprecated = true]` as usual and it flows through
+   * here.
    */
   optional bool deprecated = 6;
 }

packages/kmp/buildSrc/src/main/kotlin/org/meshtastic/proto/build/FieldMetadataRegistryHandler.kt

@@ -80,9 +80,21 @@ class FieldMetadataRegistryHandler : SchemaHandler() {
             val relative = if (packageName != null) fqn.removePrefix("$packageName.") else fqn
             val typePath = relative.split(".")
             for (field in type.fieldsAndOneOfFields) {
+                val raw = field.options.get(optionMember)
+                // `deprecated` is generator-managed (mirrored from the standard option); a
+                // hand-set value in the annotation is a hard error, matching the other
+                // generators, so they can't disagree about it.
+                val handSet = (raw as? Map<*, *>)?.keys?.any { key ->
+                    ((key as? ProtoMember)?.simpleName ?: key.toString()) == DEPRECATED_ATTR
+                } == true
+                check(!handSet) {
+                    "$fqn.${field.name}: the \"$DEPRECATED_ATTR\" attribute is generator-managed and cannot be " +
+                        "set in (meshtastic.field_metadata); mark the field `[deprecated = true]` instead and " +
+                        "it is mirrored automatically"
+                }
                 // A field earns an entry if it carries the custom annotation OR the standard
                 // `deprecated` option, which we mirror into the registry (see renderConstructor).
-                val ctor = renderConstructor(field.options.get(optionMember), field.isDeprecated, metaFieldTypes)
+                val ctor = renderConstructor(raw, field.isDeprecated, metaFieldTypes)
                     ?: continue
                 out += Entry(fqn, typePath, field.name, field.tag, ctor)
             }
@@ -96,9 +108,9 @@ class FieldMetadataRegistryHandler : SchemaHandler() {
      * Renders the `FieldMetadata(...)` constructor call for one field, or null if the field has no
      * metadata at all. [raw] is the decoded `(meshtastic.field_metadata)` option (may be null);
      * [isDeprecated] is the field's standard `deprecated` option, mirrored in as the `deprecated`
-     * attribute so apps can read deprecation at runtime. Args are keyed by attribute name (sorted,
-     * deduped) so the standard `deprecated` option is authoritative and ordering matches the other
-     * generators.
+     * attribute so apps can read deprecation at runtime (a hand-set `deprecated` in the annotation
+     * is rejected in [collect]). Args are keyed by attribute name and sorted so ordering matches
+     * the other generators.
      */
     private fun renderConstructor(
         raw: Any?,

tools/protoc-gen-fieldmeta-swift/README.md

@@ -29,8 +29,9 @@ Swift consumer doesn't need Go on contributor machines or CI.
   `[deprecated = true]` option (read off `field.options.deprecated`), not from
   the custom annotation — so fields already marked deprecated surface as
   `FieldMetadata(deprecated: true)` and apps can read deprecation at runtime.
-  Entry/attribute ordering matches the Go plugin (entries by proto type then
-  tag; accessors by type path then field name), keeping the output
+  Hand-setting `deprecated` inside the annotation is a hard error, same as the
+  Go plugin. Entry/attribute ordering matches the Go plugin (entries by proto
+  type then tag; accessors by type path then field name), keeping the output
   byte-identical even across many message types.
 
 ## Usage (Apple / swift-protobuf)

tools/protoc-gen-fieldmeta-swift/Sources/protoc-gen-fieldmeta-swift/Generator.swift

@@ -77,6 +77,14 @@ struct FieldMetaSwiftGenerator: CodeGenerator {
                 // A field earns an entry if it carries the custom annotation OR
                 // the standard `deprecated` option (which we mirror below).
                 for field in message.fields where field.options.hasFieldMetadata || field.options.deprecated {
+                    // `deprecated` is generator-managed (mirrored from the standard
+                    // option); a hand-set value in the annotation is a hard error,
+                    // matching the Go plugin, so the generators can't disagree.
+                    if field.options.fieldMetadata.hasDeprecated {
+                        throw GenError.message(
+                            "\(message.fullName).\(field.name): the \"deprecated\" attribute is generator-managed and cannot be set in (meshtastic.field_metadata); mark the field `[deprecated = true]` instead and it is mirrored automatically"
+                        )
+                    }
                     entries.append(Entry(
                         swiftTypePath: namer.fullName(message: message),
                         protoTypeName: message.fullName,

tools/protoc-gen-fieldmeta-swift/Sources/protoc-gen-fieldmeta-swift/meshtastic/field_metadata.pb.swift

@@ -112,9 +112,10 @@ public struct FieldMetadata: Sendable {
   /// Field is deprecated. MIRRORS the field's standard `[deprecated = true]`
   /// option — the generators populate this automatically from that option so
   /// every consumer can read it at runtime (protobuf runtimes strip options, so
-  /// the standard `deprecated` bit is otherwise invisible to apps). Do NOT set
-  /// this by hand in a (meshtastic.field_metadata) annotation; mark the field
-  /// `[deprecated = true]` as usual and it flows through here.
+  /// the standard `deprecated` bit is otherwise invisible to apps). Setting it
+  /// by hand in a (meshtastic.field_metadata) annotation is a generation-time
+  /// ERROR; mark the field `[deprecated = true]` as usual and it flows through
+  /// here.
   public var deprecated: Bool {
     get {_deprecated ?? false}
     set {_deprecated = newValue}

tools/protoc-gen-fieldmeta/README.md

@@ -50,6 +50,15 @@ separate module, so there's no collision). Rust could instead use an inherent
 `impl` on the prost types once the Rust generation pipeline is wired into this
 repo; the standalone module is used until then.
 
+> **`target=swift` assumes `option swift_prefix = "";`** (which every
+> `meshtastic/*.proto` sets). The emitted `extension Config.PositionConfig`
+> blocks use raw proto type paths; for a file *without* that option,
+> swift-protobuf prefixes generated type names with the package name
+> (`Meshtastic_Config`), so this plugin's extensions would reference types that
+> don't exist. The pure-Swift sibling plugin derives names from swift-protobuf's
+> own namer and is immune — the divergence is caught by the parity check in CI
+> (`.github/workflows/field-metadata.yml`).
+
 The plugin reads the option **dynamically** (no generated Go bindings) and is
 generic over the contents of the `FieldMetadata` message: adding a scalar
 attribute to `field_metadata.proto` requires no change here. The `FieldMetadata`
@@ -69,10 +78,12 @@ If a module doesn't define the extension (e.g. buf generates the option-free
 and apps therefore can't read at runtime. So any field already marked
 `[deprecated = true]` shows up in the registry (`deprecated: true`) with no
 `(meshtastic.field_metadata)` annotation, and a field carrying both a custom
-attribute and `[deprecated = true]` gets both. The standard option is
-authoritative. This is the one attribute that costs a generator change (the
-sibling Kotlin/Wire and pure-Swift generators mirror it identically); every
-other attribute remains a schema-only addition.
+attribute and `[deprecated = true]` gets both. Setting `deprecated` by hand
+inside the annotation is a **hard error at generation time** (in all three
+generators) — it would create a second source of truth for the same fact. This
+is the one attribute that costs a generator change (the sibling Kotlin/Wire and
+pure-Swift generators mirror it identically); every other attribute remains a
+schema-only addition.
 
 ## Build & test
 

tools/protoc-gen-fieldmeta/generate_test.go

@@ -230,6 +230,38 @@ func TestGenerateRejectsBadTarget(t *testing.T) {
 	}
 }
 
+// TestGenerateRejectsHandSetDeprecated verifies that setting the
+// generator-managed `deprecated` attribute by hand inside the custom annotation
+// is a hard error — regardless of its value or of the standard option — instead
+// of silently producing output the other generators would disagree with.
+func TestGenerateRejectsHandSetDeprecated(t *testing.T) {
+	for name, fieldDef := range map[string]string{
+		"true, no standard option":    `uint32 p = 1 [(meshtastic.field_metadata) = { deprecated: true }];`,
+		"false, among other attrs":    `uint32 p = 1 [(meshtastic.field_metadata) = { deprecated: false, diy_only: true }];`,
+		"redundant with standard opt": `uint32 p = 1 [deprecated = true, (meshtastic.field_metadata) = { deprecated: true }];`,
+	} {
+		t.Run(name, func(t *testing.T) {
+			req := compileRequest(t, map[string]string{
+				"meshtastic/field_metadata.proto": fieldMetadataProtoSrc,
+				"meshtastic/test.proto": `
+syntax = "proto3";
+package meshtastic;
+import "meshtastic/field_metadata.proto";
+message M { ` + fieldDef + ` }
+`,
+			}, "python", "meshtastic/test.proto", "meshtastic/field_metadata.proto")
+
+			_, err := generate(req)
+			if err == nil {
+				t.Fatal("expected error for hand-set deprecated attribute, got nil")
+			}
+			if !strings.Contains(err.Error(), "meshtastic.M.p") || !strings.Contains(err.Error(), "generator-managed") {
+				t.Errorf("error should name the field and the rule, got: %v", err)
+			}
+		})
+	}
+}
+
 // TestGenerateRejectsNonScalarAttribute verifies the scalar-only guard: a
 // non-scalar FieldMetadata attribute (here a repeated field) must fail the build
 // rather than emit meaningless, non-deterministic output.

tools/protoc-gen-fieldmeta/main.go

@@ -152,13 +152,19 @@ func generate(req *pluginpb.CodeGeneratorRequest) (*pluginpb.CodeGeneratorRespon
 	}
 
 	var entries []entry
+	var collectErr error
 	files.RangeFiles(func(fd protoreflect.FileDescriptor) bool {
 		if len(toGen) > 0 && !toGen[fd.Path()] {
 			return true
 		}
-		collectMessages(fd.Messages(), extType, resolver, &entries)
+		if collectErr = collectMessages(fd.Messages(), extType, resolver, &entries); collectErr != nil {
+			return false
+		}
 		return true
 	})
+	if collectErr != nil {
+		return nil, collectErr
+	}
 
 	sort.Slice(entries, func(i, j int) bool {
 		if entries[i].MessageType != entries[j].MessageType {
@@ -235,7 +241,7 @@ func isScalarKind(k protoreflect.Kind) bool {
 	return isIntKind(k)
 }
 
-func collectMessages(msgs protoreflect.MessageDescriptors, extType protoreflect.ExtensionType, resolver *protoregistry.Types, out *[]entry) {
+func collectMessages(msgs protoreflect.MessageDescriptors, extType protoreflect.ExtensionType, resolver *protoregistry.Types, out *[]entry) error {
 	for i := 0; i < msgs.Len(); i++ {
 		md := msgs.Get(i)
 		// Package-relative path, e.g. meshtastic.Config.PositionConfig -> [Config, PositionConfig].
@@ -245,10 +251,18 @@ func collectMessages(msgs protoreflect.MessageDescriptors, extType protoreflect.
 		for j := 0; j < fields.Len(); j++ {
 			f := fields.Get(j)
 			mf := readMetadata(f, extType, resolver)
-			// Mirror the standard `deprecated` field option into the registry.
-			// The custom annotation isn't expected to set it (see
-			// field_metadata.proto); the standard option is authoritative, so
-			// upsert to a single deprecated=true attribute either way.
+			// `deprecated` is generator-managed: it mirrors the field's standard
+			// option, and a hand-set value in the annotation is rejected rather
+			// than merged — the generators would otherwise disagree about it (the
+			// Swift plugin reads only the standard option), and the schema would
+			// carry two sources of truth for the same fact.
+			for _, a := range mf {
+				if a.Name == deprecatedAttr {
+					return fmt.Errorf(
+						"%s.%s: the %q attribute is generator-managed and cannot be set in (meshtastic.field_metadata); mark the field `[deprecated = true]` instead and it is mirrored automatically",
+						md.FullName(), f.Name(), deprecatedAttr)
+				}
+			}
 			if fieldIsDeprecated(f) {
 				mf = upsertBool(mf, deprecatedAttr, true)
 			}
@@ -263,8 +277,11 @@ func collectMessages(msgs protoreflect.MessageDescriptors, extType protoreflect.
 				Fields:      mf,
 			})
 		}
-		collectMessages(md.Messages(), extType, resolver, out) // nested message types
+		if err := collectMessages(md.Messages(), extType, resolver, out); err != nil { // nested message types
+			return err
+		}
 	}
+	return nil
 }
 
 // readMetadata returns the set attributes of the field_metadata option on a