docs: align contracts and Firebase fixture dependencies

docs.json

@@ -75,7 +75,7 @@
   ],
   "variables": {
     "versions": {
-      "default": "1.0.0",
+      "default": "1.1.0",
       "isPrerelease": false
     }
   },

docs/api-reference/index.mdx

@@ -16,8 +16,9 @@ Entry point for creating schemas. See [Schema Types](../core-concepts/schemas.md
 - `Ack.list(AckSchema itemSchema)`: Creates a `ListSchema` for validating arrays. Nullable item schemas are not supported; make the list itself nullable instead.
 - `Ack.object(Map<String, AckSchema> properties)`: Creates an `ObjectSchema` for validating objects.
 - `Ack.enumValues(List<T> values)`: Creates an `EnumSchema<T>` for Dart enum
-  types. Accepts enum instances, string names, or indices. **Preferred over
-  `enumString` when a Dart enum exists.**
+  types. Parses enum `.name` strings into typed enum values. Pass typed enum
+  values to `encode` or `safeEncode` for the reverse direction. **Preferred
+  over `enumString` when a Dart enum exists.**
 - `Ack.enumCodec(List<T> values)`: Like `enumValues`, but returns a
   `CodecSchema<String, T>` instead of an `EnumSchema<T>`. Use this when
   downstream code expects every value-shape to be a `CodecSchema` (e.g. a
@@ -33,9 +34,11 @@ Entry point for creating schemas. See [Schema Types](../core-concepts/schemas.md
 - `Ack.codec(...)` / `Ack.date()` / `Ack.datetime()` / `Ack.uri()` /
   `Ack.duration()` / `Ack.enumCodec(...)`: Create codecs. See
   [Codecs](../core-concepts/codecs.mdx).
-- `Ack.lazy(String name, AckSchema Function() builder)`: Creates a memoized
-  deferred schema reference for recursive schema graphs. JSON Schema export
-  renders Draft-7 `definitions` / `$ref` entries using `name`.
+- `Ack.lazy(String name, AckSchema Function() builder, {int maxDepth = 100})`:
+  Creates a memoized deferred schema reference for recursive schema graphs.
+  `maxDepth` must be at least `1` and limits parsing, runtime validation, and
+  encoding. JSON Schema export renders Draft-7 `definitions` / `$ref` entries
+  using `name` but warns that the runtime-only depth limit was omitted.
 - `Ack.discriminated<T extends Object>(...)`: Creates a discriminated union
   schema. Branches may be plain `ObjectSchema` or transformed schemas whose
   base is an `ObjectSchema`. The union owns the discriminator: branches normally
@@ -49,7 +52,10 @@ Base class for all schema types.
 
 ### Primary Validation Methods
 
-- `SchemaResult<Runtime> safeParse(Object? data, {String? debugName})`: Validates `data` and returns a `SchemaResult`. Never throws; use `.getOrNull()` to get the value without risk of an exception.
+- `SchemaResult<Runtime> safeParse(Object? data, {String? debugName})`: Validates
+  `data` and returns a `SchemaResult`. Invalid input and recoverable `Exception`
+  values thrown by validation callbacks become failures. Programmer/runtime
+  `Error` values are rethrown with their original stack trace.
 - `Runtime? parse(Object? data, {String? debugName})`: Validates `data` and returns the value; throws `AckException` on failure.
 - `SchemaResult<TOut> safeParseAs<TOut extends Object>(Object? data, TOut Function(Runtime?) map, {String? debugName})`: Parses and maps the validated value to `TOut`.
 - `TOut parseAs<TOut extends Object>(Object? data, TOut Function(Runtime?) map, {String? debugName})`: Throwing variant of `safeParseAs`.
@@ -101,7 +107,7 @@ Schema for validating strings. See [String Validation](../core-concepts/validati
 
 - `email()`: Must be valid email format
 - `url()`: Must be valid URL format (alias for `uri()`)
-- `uri()`: Must be valid URI according to RFC 3986
+- `uri()`: Must be a valid absolute URI with a scheme and host
 - `uuid()`: Must be valid UUID format
 - `ip({int? version})`: Must be valid IP address (version 4 or 6)
 - `ipv4()`: Must be valid IPv4 address
@@ -189,9 +195,11 @@ Represents a validation failure. See [Error handling](../core-concepts/error-han
 - `SchemaContext context`: Context about where the error occurred.
 
 **Subclasses:**
+- `TypeMismatchError`: The input has the wrong Dart runtime type.
 - `SchemaConstraintsError`: One or more constraint violations.
 - `SchemaNestedError`: Validation failures in nested objects or arrays.
 - `SchemaValidationError`: Custom refinement failures.
+- `SchemaTransformError`: Decode/transform callback failures.
 - `SchemaEncodeError`: Encode-path failures (non-nullable null, one-way transform, encoder threw, etc.).
 
 ## `Constraint<T>`
@@ -235,10 +243,15 @@ Schema for polymorphic validation based on a string discriminator property.
 
 Schema reference for recursive object graphs.
 
-- Created using `Ack.lazy<Boundary, Runtime>(name, builder)`.
+- Created using `Ack.lazy<Boundary, Runtime>(name, builder)`. `maxDepth`
+  defaults to `100` and must be at least `1`; pass it explicitly only to
+  override the default.
 - The builder is resolved once and memoized.
+- Exceeding `maxDepth` returns a validation failure during parsing, runtime
+  validation, or encoding.
 - `toJsonSchema()` and `toSchemaModel()` export Draft-7 `definitions` / `$ref`
-  entries using the lazy `name`.
+  entries using the lazy `name`. The runtime-only depth limit cannot be
+  represented by `$ref`, so exported schema models warn that it was omitted.
 - Bare or wrapped lazy schemas cannot be used as discriminated-union branches
   because the branch discriminator must be analyzable at construction time.
 
@@ -290,7 +303,9 @@ print(user.email); // Type-safe String access
 
 ### `EnumSchema<T>`
 
-Schema for validating enum values. Created using `Ack.enumValues(List<T> values)` where `T extends Enum`.
+Schema for mapping enum `.name` strings at the boundary to typed enum values at
+runtime. Created using `Ack.enumValues(List<T> values)` where `T extends Enum`;
+`encode` and `safeEncode` map typed enum values back to their names.
 
 ### `AnyOfSchema`
 

docs/core-concepts/schemas.mdx

@@ -203,7 +203,10 @@ categorySchema = Ack.object({
 
 The lazy builder is resolved once and memoized. JSON Schema export renders the
 reference through Draft-7 `definitions` / `$ref`, so recursive children are
-referenced rather than inlined forever.
+referenced rather than inlined forever. `maxDepth` defaults to `100`, must be at
+least `1`, and returns a validation failure when parsing, runtime validation, or
+encoding exceeds the limit. Because the limit is runtime-only and cannot be
+represented by `$ref`, exported schema models warn that it was omitted.
 
 ### Any
 

docs/core-concepts/validation.mdx

@@ -97,7 +97,9 @@ Ack.string().time()
 ```
 
 ### `uri()`
-Requires a valid URI per RFC 3986.
+Requires a valid absolute URI with a scheme and host. This is the network-URI
+subset Ack accepts, rather than every relative or non-host URI permitted by RFC
+3986.
 ```dart
 Ack.string().uri()
 ```

docs/getting-started/quickstart-tutorial.mdx

@@ -25,7 +25,10 @@ See [Schema Types](../core-concepts/schemas.mdx) and [Validation Rules](../core-
 
 ## 2. Validate data
 
-Call `safeParse()` with the data you received — for example `jsonDecode(response.body)`. It returns a `SchemaResult` and never throws.
+Call `safeParse()` with the data you received — for example
+`jsonDecode(response.body)`. It returns a `SchemaResult` for invalid input and
+for recoverable `Exception` values thrown by validation callbacks.
+Programmer/runtime `Error` values are rethrown with their original stack trace.
 
 ```dart
 final result = userSchema.safeParse({'name': 'Alice', 'age': 30});

llms.txt

@@ -173,8 +173,9 @@ AckType generation is intentionally strict:
 
 - `schema.parse(data)` throws on invalid input
 - `schema.safeParse(data)` returns `SchemaResult<T>`
-- `safeParse` does not throw; exceptions from validation/refinement callbacks
-  are returned as contextual validation failures
+- `safeParse` turns invalid input and recoverable `Exception` values from
+  validation/refinement callbacks into contextual failures
+- programmer/runtime `Error` values are rethrown with their original stack trace
 - `SchemaResult<T>.getOrThrow()` returns the validated value or throws `AckException`
 - `.optional()` allows a field to be omitted
 - `.nullable()` allows a present field to hold `null`
@@ -183,6 +184,8 @@ AckType generation is intentionally strict:
 - `schema.toJsonSchema()` renders `schema.toSchemaModel().toJsonSchema()`
 - adapter packages should render from `AckSchemaModel`, not by traversing `AckSchema` subclasses
 - `Ack.list(...)` does not support nullable item schemas; make the list itself nullable when needed
+- `Ack.lazy(...)` defaults `maxDepth` to `100` for recursive parsing, runtime
+  validation, and encoding; the runtime-only limit is omitted from exported schemas with a warning
 - `Ack.object`, `Ack.anyOf`, and enum factories snapshot their input collections;
   unions and enum value lists must be non-empty, and enum values must be unique
 - lengths and item counts must be non-negative; numeric bounds must be finite;

packages/ack_firebase_ai/README.md

@@ -25,7 +25,7 @@ Always validate model output with the same ACK schema after generation. Firebase
 dependencies:
   ack: ^1.0.0
   ack_firebase_ai: ^1.0.0
-  firebase_ai: ^3.12.1
+  firebase_ai: ^3.12.2
 ```
 
 This package targets Firebase AI's map-based `responseJsonSchema` API for models that support JSON Schema structured output.

packages/ack_firebase_ai/pubspec.yaml

@@ -15,9 +15,12 @@ dependencies:
     sdk: flutter
 
 dev_dependencies:
-  firebase_core: ^4.9.0
-  firebase_core_platform_interface: ^7.0.1
-  firebase_ai: '>=3.12.1 <3.13.0'
+  # Keep the generated Firebase fixture and its compile-time SDK matrix exact.
+  firebase_ai: 3.12.2
+  firebase_app_check: 0.4.5
+  firebase_auth: 6.5.4
+  firebase_core: 4.11.0
+  firebase_core_platform_interface: 7.1.0
   flutter_test:
     sdk: flutter
   lints: ^5.0.0

packages/ack_generator/README.md

@@ -79,6 +79,9 @@ validate through the union's effective branch.
 - Inline anonymous object branches are rejected for typed generation. Extract
   them to a named top-level schema first.
 - Nullable top-level schemas do not emit extension types.
+- Nullable list elements are rejected: `Ack.list(item.nullable())` is not
+  supported. Make the list nullable with `Ack.list(item).nullable()` when the
+  list itself may be `null`.
 - `@AckType()` requires static schema resolution for nested object references.
 
 ## Build commands