feat(dart): Introduce id based enum serialization

[yash-agarwa-l]

Why?

The Dart module, only supports ordinal enum serialization, where each enum
value is serialized as its position index (0, 1, 2...), which breaks in different
cases like adding or reordering values. This adds optional id based serialization
with so that we can provide unique id to every while preserving ordinal serialization
as the default fallback.

What does this PR do?

• Adds @ForyEnumId(int id) for enum values
• Registers ForyEnumId in analysis type detection
• Updates enum analysis to collect IDs and emit build-time warnings for:
  - partial @ForyEnumId usage
  - duplicate IDs
• Falls back to ordinal serialization when annotations are incomplete or duplicated
• Extends EnumSpec with an optional idToValue map
• Updates generated enum specs to include the ID map when valid
• Updates EnumSerializer to use ID-based read/write when the map is present, otherwise keep ordinal behavior
• Adds codegen and serializer tests

Related issues

AI Contribution Checklist

AI Usage Disclosure
AI assistance was used to suggest tests and for better warnings in enum_analyzer.
dart/packages/fory/lib/src/codegen/analyze/impl/struct/enum_analyzer_impl.dart
dart/packages/fory-test/test/

• I included a completed AI Contribution Checklist in this PR description and the required AI Usage Disclosure.
• I can explain and defend all important changes without AI help.
• I reviewed AI-assisted code changes line by line before submission.
• I ran adequate human verification and recorded evidence (checks run locally or in CI, pass/fail summary, and confirmation I reviewed results).
• I added/updated tests and specs where required.
• I validated protocol/performance impacts with evidence when applicable.
• I verified licensing and provenance compliance.

Does this PR introduce any user-facing change?

• Does this PR introduce any public API change?
  @ForyEnumId is a new annotation users will write in their code
  ForyEnumId class is publicly accessible
• Does this PR introduce any binary protocol compatibility change?

Benchmark

General struct performance remained similar because those benchmarks do not exercise enum serialization paths.

[yash-agarwa-l]

Firstly, Thank you sm for the clarification about this in the discussions, it took some time to complete it.
Few Questions:

• Shall I create an issue for this and tag it there?
• And I did a performance test by creating a different file specific to enums, shall I add that?

[chaokunyang]

Could we also support this pattern?

@ ForyEnum()
enum UserRole {
  guest(0),
  member(1),
  admin(2);

  @ForyEnumId()
  final int code;

  const UserRole(this.code);
}

[chaokunyang]

use uppercase?

[yash-agarwa-l]

Yes, we should do it as per conventions, but the existing files also follow the same pattern. If you prefer, shall I make a separate PR for that first before this one?

[yash-agarwa-l]

Could we also support this pattern?

@ ForyEnum()
enum UserRole {
  guest(0),
  member(1),
  admin(2);

  @ForyEnumId()
  final int code;

  const UserRole(this.code);
}

Yes, I had this in mind initially too. I went with per-value annotation because I feel the id is a metadata for values and since Dart enums don't support private fields, so the foryId ends up publicly accessible in user's code which felt a bit annoying. But I agree the field-based approach looks much cleaner for long enums. I'd be happy to change it if you prefer.

[chaokunyang]

Sometimes users also want to use that id too. So I think we could support both. Could you support both in this pr?

[yash-agarwa-l]

Yes, we can do that! I have updated the PR to support both methods and added the relevant tests.

[chaokunyang]

Validate @ForyEnumId range before generating enum specs

This accepts any int from @ForyEnumId and later feeds it to writeVarUint32Small7(...). Negative values do not fail cleanly here: I reproduced writeVarUint32Small7(-1) decoding back as 34359738367, so @ForyEnumId(-1) silently writes a different wire id than the one the user declared. Please reject ids outside the unsigned 32-bit range during analysis, and ideally keep a serializer-side assertion as defense in depth.

[chaokunyang]

Add a public Fory round-trip for annotated enums

These tests prove the generated EnumSpec shape and the direct EnumSerializer behavior, but they still do not exercise the public Fory.serialize / Fory.deserialize path with an annotated enum. That leaves a gap around the real registration and resolver wiring for this new feature. Please add at least one end-to-end round-trip test for an enum that uses @ForyEnumId.

[yash-agarwa-l]

Thanks for the review! Now, For the codegen path, if Ids are out of range it fall back to ordinal serialization with a warning while EnumSerializer.write() throw a RangeError for manually constructed specs.
Is this fine? Or shall we also give a hard error through the codegen?

[chaokunyang]

Thanks for the review! Now, For the codegen path, if Ids are out of range it fall back to ordinal serialization with a warning while EnumSerializer.write() throw a RangeError for manually constructed specs. Is this fine? Or shall we also give a hard error through the codegen?

Need strict errors instead

[yash-agarwa-l]

I've added the round-trip tests and updated for out-of-range. Should missingIdValues and duplicateIds also be strict? I think they cause a similar problem.

[chaokunyang]

I've added the round-trip tests and updated for out-of-range. Should missingIdValues and duplicateIds also be strict? I think they cause a similar problem.

Yes. missingIdValues and duplicateIds should also be strict.

The rule should be:

• No @ForyEnumId anywhere: use ordinal mode.
• Any @ForyEnumId present: the whole enum ID configuration must be valid, or codegen should fail.

[yash-agarwa-l]

Thanks! I have made the revision.