Add GeneratorVersion enum to enforce compatible generated sources

Author: greenrobot

generator/lib/src/code_chunks.dart

@@ -104,6 +104,11 @@ class CodeChunks {
   static String defineModel(ModelInfo model) {
     return '''
     final model = $obxInt.ModelInfo(
+      // If this version is not found, it means that this file was generated
+      // with an older version of the ObjectBox Dart generator.
+      // Please regenerate this file with the current generator version.
+      // Typically, this is done with `dart run build_runner build`.
+      generatorVersion: $obxInt.GeneratorVersion.${generatorVersionLatest.name},
       entities: _entities,
       lastEntityId: ${createIdUid(model.lastEntityId)},
       lastIndexId: ${createIdUid(model.lastIndexId)},

generator/test/code_builder_test.dart

@@ -1,3 +1,4 @@
+import 'dart:convert';
 import 'dart:io';
 
 import 'package:logging/logging.dart';
@@ -953,4 +954,32 @@ void main() {
       );
     });
   });
+
+  group('GeneratorVersion', () {
+    test('generated code includes GeneratorVersion parameter', () async {
+      final source = r'''
+      library example;     
+      import 'package:objectbox/objectbox.dart';
+      
+      @Entity()
+      class Example {
+        @Id()
+        int id = 0;
+      }
+      ''';
+
+      final testEnv = GeneratorTestEnv();
+      // Verify the generated code contains the GeneratorVersion parameter.
+      // The matcher receives bytes, so use predicate to convert to string.
+      final expectedVersion =
+          'generatorVersion: obx_int.GeneratorVersion.${generatorVersionLatest.name}';
+      await testEnv.run(
+        source,
+        generatedCodeMatcher: predicate<List<int>>(
+          (bytes) => utf8.decode(bytes).contains(expectedVersion),
+          'contains "$expectedVersion"',
+        ),
+      );
+    });
+  });
 }

generator/test/generator_test_env.dart

@@ -38,6 +38,7 @@ class GeneratorTestEnv {
   Future<GeneratorTestResult> run(
     String source, {
     bool ignoreOutput = false,
+    Object? generatedCodeMatcher,
   }) async {
     final library = "example";
     // Enable resolving imports (imported packages must be a dependency of this package)
@@ -55,7 +56,7 @@ class GeneratorTestEnv {
       //   var modelEntity = ModelEntity.fromMap(entitiesList[0], check: false);
       //   return modelEntity.name == "Example" && modelEntity.flags == 0;
       // }),
-      '$library|lib/objectbox.g.dart': isNotNull,
+      '$library|lib/objectbox.g.dart': generatedCodeMatcher ?? isNotNull,
       // Future improvement: assert generated code? Needs existing model JSON for stable IDs
       // '$library|lib/objectbox.g.dart': '<file-content>'
     };

objectbox/lib/src/modelinfo/modelinfo.dart

@@ -8,6 +8,28 @@ import 'modelentity.dart';
 const _minModelVersion = 5;
 const _maxModelVersion = 5;
 
+/// Represents the generator version used to create the model.
+///
+/// This enum contains all supported versions by this ObjectBox runtime library.
+/// It is used purely for compile-time enforcement to ensure users regenerate
+/// code after updating the objectbox package.
+/// Once a version is not compatible/supported, it is removed from this enum.
+/// Note: using a separate, date based, versioning (YYYY_MM_DD) as the
+/// generator is not always updated in each library version.
+enum GeneratorVersion {
+  /// The model was not created by generated code.
+  none,
+
+  /// BREAKING CHANGE in ObjectBox Dart 5.1 with DateTime (date) properties:
+  /// - DateTime properties are now stored in UTC by default(!).
+  /// - If you rely on reading local time, you must use dateLegacy.
+  /// - Only UTC times provide correct values for ObjectBox Sync.
+  v2025_12_16,
+}
+
+/// The latest generator version (aligned with this ObjectBox runtime library).
+const generatorVersionLatest = GeneratorVersion.v2025_12_16;
+
 /// In order to represent the model stored in `objectbox-model.json` in Dart,
 /// several classes have been introduced. Conceptually, these classes are
 /// comparable to how models are handled in ObjectBox Java and ObjectBox Go.
@@ -20,6 +42,9 @@ class ModelInfo {
     'If you have VCS merge conflicts, you must resolve them according to ObjectBox docs.',
   ];
 
+  /// The ObjectBox Dart generator version used to generate this model.
+  GeneratorVersion generatorVersion;
+
   List<ModelEntity> entities;
   IdUid lastEntityId, lastIndexId, lastRelationId, lastSequenceId;
   List<int> retiredEntityUids,
@@ -29,7 +54,8 @@ class ModelInfo {
   int modelVersion, modelVersionParserMinimum, version;
 
   ModelInfo(
-      {required this.entities,
+      {required this.generatorVersion,
+      required this.entities,
       required this.lastEntityId,
       required this.lastIndexId,
       required this.lastRelationId,
@@ -43,7 +69,8 @@ class ModelInfo {
       required this.version});
 
   ModelInfo.empty()
-      : entities = [],
+      : generatorVersion = GeneratorVersion.none,
+        entities = [],
         lastEntityId = const IdUid.empty(),
         lastIndexId = const IdUid.empty(),
         lastRelationId = const IdUid.empty(),
@@ -57,7 +84,8 @@ class ModelInfo {
         version = 1;
 
   ModelInfo.fromMap(Map<String, dynamic> data, {bool check = true})
-      : entities = [],
+      : generatorVersion = GeneratorVersion.none,
+        entities = [],
         lastEntityId = IdUid.fromString(data['lastEntityId'] as String?),
         lastIndexId = IdUid.fromString(data['lastIndexId'] as String?),
         lastRelationId = IdUid.fromString(data['lastRelationId'] as String?),