refactor: consolidate duplicated guards, error construction, and package list

Behavior-preserving simplifications on top of the validation/schema/tooling
fixes. Each item removes a single source of duplication or redundant state:

- ack.dart: extract _requireNonEmpty/_requireUniqueBy for the enumValues,
  enumString, and anyOf argument guards
- schema.dart: extract _failFromThrown for the three thrown-error catch blocks
- codec_schema.dart: drop redundant _encoderIdentity (provably identical to
  _encoder in every path; _decoderIdentity retained as it fixes a real bug)
- lazy_schema.dart: drop write-only _LazyRecursionContext.owner (duplicated the
  inherited SchemaContext.schema)
- ack_schema_model_builder.dart: hoist a single const _deepEquality
- schema_ast_analyzer.dart: extract _rejectIfReferencesNullableSchema (2 sites)
- api_check.dart: extract _writeProcessStderr
- update_release_changelog.dart: drop redundant record `path` field
- scripts: share publishableAckPackages across api_check and
  update_release_changelog (new scripts/src/workspace_packages.dart)
- enum_schema/any_of_schema: point docs to the canonical AckSchema policy

dart analyze clean; ack (955) + ack_generator (127) + scripts tests pass.

Author: leoafarias

packages/ack/lib/src/ack.dart

@@ -52,13 +52,8 @@ final class Ack {
 
   /// Creates an enum schema for validating enum values.
   static EnumSchema<T> enumValues<T extends Enum>(List<T> values) {
-    if (values.isEmpty) {
-      throw ArgumentError.value(values, 'values', 'Must not be empty.');
-    }
-    final names = values.map((value) => value.name).toSet();
-    if (names.length != values.length) {
-      throw ArgumentError.value(values, 'values', 'Must be unique.');
-    }
+    _requireNonEmpty(values, 'values');
+    _requireUniqueBy(values, 'values', (value) => value.name);
     return EnumSchema(values: List.unmodifiable(values));
   }
 
@@ -79,22 +74,16 @@ final class Ack {
 
   /// Creates a string schema that only accepts one of the given [values].
   static StringSchema enumString(List<String> values) {
-    if (values.isEmpty) {
-      throw ArgumentError.value(values, 'values', 'Must not be empty.');
-    }
-    if (values.toSet().length != values.length) {
-      throw ArgumentError.value(values, 'values', 'Must be unique.');
-    }
+    _requireNonEmpty(values, 'values');
+    _requireUniqueBy(values, 'values', (value) => value);
     return string().withConstraint(
       PatternConstraint.enumString(List.unmodifiable(values)),
     );
   }
 
   /// Creates a schema that can be one of many types.
   static AnyOfSchema anyOf(List<AnyAckSchema> schemas) {
-    if (schemas.isEmpty) {
-      throw ArgumentError.value(schemas, 'schemas', 'Must not be empty.');
-    }
+    _requireNonEmpty(schemas, 'schemas');
     return AnyOfSchema(List.unmodifiable(schemas));
   }
 
@@ -269,3 +258,21 @@ String _encodeIsoDate(DateTime value) {
 String _encodeIsoDateTime(DateTime value) {
   return value.toIso8601String();
 }
+
+List<T> _requireNonEmpty<T>(List<T> values, String name) {
+  if (values.isEmpty) {
+    throw ArgumentError.value(values, name, 'Must not be empty.');
+  }
+  return values;
+}
+
+List<T> _requireUniqueBy<T, K>(
+  List<T> values,
+  String name,
+  K Function(T) keyOf,
+) {
+  if (values.map(keyOf).toSet().length != values.length) {
+    throw ArgumentError.value(values, name, 'Must be unique.');
+  }
+  return values;
+}

packages/ack/lib/src/schema_model/ack_schema_model_builder.dart

@@ -10,6 +10,8 @@ import '../schemas/schema.dart';
 import 'ack_schema_model.dart';
 import 'ack_schema_model_warning.dart';
 
+const _deepEquality = DeepCollectionEquality();
+
 extension AckSchemaModelExtension<
   Boundary extends Object,
   Runtime extends Object
@@ -47,10 +49,9 @@ final class _SchemaModelBuilder {
       merged[key] = entry.value;
     }
 
-    const equality = DeepCollectionEquality();
     for (final entry in lazyDefinitions.entries) {
       if (merged.containsKey(entry.key)) {
-        if (!equality.equals(merged[entry.key], entry.value)) {
+        if (!_deepEquality.equals(merged[entry.key], entry.value)) {
           throw ArgumentError(
             'Ack.lazy definition "${entry.key}" collides with an existing root '
             'JSON Schema definition. Use a unique lazy name or rename the '
@@ -353,7 +354,6 @@ AckSchemaModel _applyConstraints(
   AckSchema<dynamic, dynamic> schema,
 ) {
   var next = model;
-  const deepEquality = DeepCollectionEquality();
   final appliedKeywordValues = {
     for (final entry in _renderedKeywords(model).entries)
       entry.key: <Object?>[entry.value],
@@ -374,7 +374,7 @@ AckSchemaModel _applyConstraints(
           appliedKeywordValues[entry.key] = [entry.value];
           newKeywords[entry.key] = entry.value;
         } else if (!seenValues.any(
-          (value) => deepEquality.equals(value, entry.value),
+          (value) => _deepEquality.equals(value, entry.value),
         )) {
           seenValues.add(entry.value);
           conflicts[entry.key] = entry.value;

packages/ack/lib/src/schemas/any_of_schema.dart

@@ -14,7 +14,7 @@ final class AnyOfSchema extends AckSchema<Object, Object>
 
   /// Creates a low-level union from an immutable, non-empty list of [schemas].
   ///
-  /// Prefer `Ack.anyOf`, which validates and snapshots caller-owned lists.
+  /// See [AckSchema] for the low-level-constructor policy; prefer [Ack.anyOf].
   /// Direct callers must not mutate [schemas] after construction.
   const AnyOfSchema(
     this.schemas, {

packages/ack/lib/src/schemas/codec_schema.dart

@@ -25,24 +25,21 @@ final class CodecSchema<Boundary extends Object, Runtime extends Object>
   final Runtime Function(Object value) _decoder;
   final Object Function(Runtime value)? _encoder;
   final Object _decoderIdentity;
-  final Object? _encoderIdentity;
 
   CodecSchema._({
     required this.inputSchema,
     required this.outputSchema,
     required Runtime Function(Object value) decoder,
     required Object Function(Runtime value)? encoder,
     required Object decoderIdentity,
-    required Object? encoderIdentity,
     super.isNullable,
     super.isOptional,
     super.description,
     super.constraints,
     super.refinements,
   }) : _decoder = decoder,
        _encoder = encoder,
-       _decoderIdentity = decoderIdentity,
-       _encoderIdentity = encoderIdentity;
+       _decoderIdentity = decoderIdentity;
 
   /// Creates a codec while preserving the input schema's runtime type.
   static CodecSchema<Boundary, Runtime> create<
@@ -66,7 +63,6 @@ final class CodecSchema<Boundary extends Object, Runtime extends Object>
       decoder: (value) => decoder(value as InputRuntime),
       encoder: encoder,
       decoderIdentity: decoder,
-      encoderIdentity: encoder,
       isNullable: isNullable,
       isOptional: isOptional,
       description: description,
@@ -169,7 +165,6 @@ final class CodecSchema<Boundary extends Object, Runtime extends Object>
       decoder: _decoder,
       encoder: _encoder,
       decoderIdentity: _decoderIdentity,
-      encoderIdentity: _encoderIdentity,
       isNullable: isNullable,
       isOptional: isOptional,
       description: description,
@@ -192,7 +187,6 @@ final class CodecSchema<Boundary extends Object, Runtime extends Object>
       decoder: _decoder,
       encoder: _encoder,
       decoderIdentity: _decoderIdentity,
-      encoderIdentity: _encoderIdentity,
       isNullable: isNullable ?? this.isNullable,
       isOptional: isOptional ?? this.isOptional,
       description: description ?? this.description,
@@ -210,7 +204,7 @@ final class CodecSchema<Boundary extends Object, Runtime extends Object>
         inputSchema == other.inputSchema &&
         outputSchema == other.outputSchema &&
         _decoderIdentity == other._decoderIdentity &&
-        _encoderIdentity == other._encoderIdentity;
+        _encoder == other._encoder;
   }
 
   @override
@@ -225,6 +219,6 @@ final class CodecSchema<Boundary extends Object, Runtime extends Object>
     inputSchema,
     outputSchema,
     _decoderIdentity,
-    _encoderIdentity,
+    _encoder,
   );
 }

packages/ack/lib/src/schemas/enum_schema.dart

@@ -10,8 +10,9 @@ final class EnumSchema<T extends Enum> extends AckSchema<String, T>
   /// Creates a low-level enum schema from an immutable, non-empty set of
   /// uniquely named [values].
   ///
-  /// Prefer `Ack.enumValues`, which validates and snapshots caller-owned lists.
-  /// Direct callers must not mutate [values] after construction.
+  /// See [AckSchema] for the low-level-constructor policy; prefer
+  /// [Ack.enumValues]. Direct callers must not mutate [values] after
+  /// construction.
   const EnumSchema({
     required this.values,
     super.isNullable,

packages/ack/lib/src/schemas/lazy_schema.dart

@@ -132,7 +132,7 @@ final class LazySchema<Boundary extends Object, Runtime extends Object>
   SchemaContext _enterRecursion(Object? value, SchemaContext context) {
     return _LazyRecursionContext(
       name: name,
-      owner: this as AnyAckSchema,
+      schema: this as AnyAckSchema,
       recursionToken: _recursionToken,
       value: value,
       parent: context,
@@ -222,20 +222,19 @@ final class LazySchema<Boundary extends Object, Runtime extends Object>
 final class _LazyRecursionContext extends SchemaContext {
   _LazyRecursionContext({
     required String name,
-    required this.owner,
+    required AnyAckSchema schema,
     required this.recursionToken,
     required Object? value,
     required SchemaContext parent,
   }) : super(
          name: name,
-         schema: owner,
+         schema: schema,
          value: value,
          parent: parent,
          pathSegment: '',
          operation: parent.operation,
        );
 
-  final AnyAckSchema owner;
   final Object recursionToken;
 }
 

packages/ack/lib/src/schemas/schema.dart

@@ -150,13 +150,11 @@ abstract class AckSchema<Boundary extends Object, Runtime extends Object> {
         final violation = constraint.validate(value);
         if (violation != null) constraintViolations.add(violation);
       } catch (error, stackTrace) {
-        return SchemaResult.fail(
-          SchemaValidationError(
-            message: 'Constraint "${constraint.constraintKey}" threw: $error',
-            context: context,
-            cause: error,
-            stackTrace: stackTrace,
-          ),
+        return _failFromThrown(
+          'Constraint "${constraint.constraintKey}" threw: $error',
+          context,
+          error,
+          stackTrace,
         );
       }
     }
@@ -177,13 +175,11 @@ abstract class AckSchema<Boundary extends Object, Runtime extends Object> {
       try {
         isValid = refinement.validate(value);
       } catch (error, stackTrace) {
-        return SchemaResult.fail(
-          SchemaValidationError(
-            message: 'Refinement threw: $error',
-            context: context,
-            cause: error,
-            stackTrace: stackTrace,
-          ),
+        return _failFromThrown(
+          'Refinement threw: $error',
+          context,
+          error,
+          stackTrace,
         );
       }
       if (!isValid) {
@@ -196,6 +192,22 @@ abstract class AckSchema<Boundary extends Object, Runtime extends Object> {
     return SchemaResult.ok(value);
   }
 
+  SchemaResult<Runtime> _failFromThrown(
+    String message,
+    SchemaContext context,
+    Object error,
+    StackTrace stackTrace,
+  ) {
+    return SchemaResult.fail(
+      SchemaValidationError(
+        message: message,
+        context: context,
+        cause: error,
+        stackTrace: stackTrace,
+      ),
+    );
+  }
+
   /// Helper for schemas whose boundary == runtime: validates the runtime
   /// value and, if it passes, returns it as the boundary value unchanged.
   /// Only safe to call when `Boundary` and `Runtime` are the same type.
@@ -361,13 +373,11 @@ abstract class AckSchema<Boundary extends Object, Runtime extends Object> {
     try {
       return parseWithContext(value, context);
     } catch (error, stackTrace) {
-      return SchemaResult.fail(
-        SchemaValidationError(
-          message: 'Validation threw: $error',
-          context: context,
-          cause: error,
-          stackTrace: stackTrace,
-        ),
+      return _failFromThrown(
+        'Validation threw: $error',
+        context,
+        error,
+        stackTrace,
       );
     }
   }

packages/ack_generator/lib/src/analyzer/schema_ast_analyzer.dart

@@ -2098,14 +2098,7 @@ class SchemaAstAnalyzer {
       }
 
       if (chain.schemaReference != null) {
-        final resolved = _resolveSchemaReference(
-          chain.schemaReference!,
-          element,
-        );
-        _rejectNullableListElement(
-          resolved?.modelInfo.isNullableSchema ?? false,
-          element,
-        );
+        _rejectIfReferencesNullableSchema(chain.schemaReference!, element);
         final mapping = _resolveSchemaVariableType(
           chain.schemaReference!,
           element,
@@ -2168,11 +2161,7 @@ class SchemaAstAnalyzer {
     }
 
     if (ref.schemaRef != null) {
-      final resolved = _resolveSchemaReference(ref.schemaRef!, element);
-      _rejectNullableListElement(
-        resolved?.modelInfo.isNullableSchema ?? false,
-        element,
-      );
+      _rejectIfReferencesNullableSchema(ref.schemaRef!, element);
       final mapping = _resolveSchemaVariableType(
         ref.schemaRef!,
         element,
@@ -2207,6 +2196,17 @@ class SchemaAstAnalyzer {
     );
   }
 
+  void _rejectIfReferencesNullableSchema(
+    _SchemaReference reference,
+    Element2 element,
+  ) {
+    final resolved = _resolveSchemaReference(reference, element);
+    _rejectNullableListElement(
+      resolved?.modelInfo.isNullableSchema ?? false,
+      element,
+    );
+  }
+
   _SchemaTypeMapping _wrapListElementMapping(
     _SchemaTypeMapping elementMapping,
     TypeProvider typeProvider,

scripts/api_check.dart

@@ -3,13 +3,9 @@
 import 'dart:convert';
 import 'dart:io';
 
-const ackPackages = [
-  'ack',
-  'ack_annotations',
-  'ack_generator',
-  'ack_firebase_ai',
-  'ack_json_schema_builder',
-];
+import 'src/workspace_packages.dart';
+
+final ackPackages = publishableAckPackages;
 const dartApiToolVersion = '0.23.0';
 
 Future<void> main(List<String> args) async {
@@ -164,9 +160,7 @@ Future<bool> checkPackage(
     print('✅ $packageName: API check completed');
   } else {
     stderr.writeln('❌ $packageName: API changes detected or check failed');
-    if ((result.stderr as String).isNotEmpty) {
-      stderr.writeln(result.stderr);
-    }
+    _writeProcessStderr(result);
   }
 
   final reportExists = report.existsSync();
@@ -185,15 +179,19 @@ Future<bool> runCommand(String command, List<String> args) async {
     if (result.exitCode == 0) return true;
 
     stderr.writeln('Error running $command ${args.join(' ')}');
-    if ((result.stderr as String).isNotEmpty) {
-      stderr.writeln(result.stderr);
-    }
+    _writeProcessStderr(result);
   } on ProcessException catch (error) {
     stderr.writeln('Error running $command ${args.join(' ')}: $error');
   }
   return false;
 }
 
+void _writeProcessStderr(ProcessResult result) {
+  if ((result.stderr as String).isNotEmpty) {
+    stderr.writeln(result.stderr);
+  }
+}
+
 void printUsage() {
   print('');
   print('Usage: dart scripts/api_check.dart [PACKAGE] [VERSION]');