conformly 0.7.2__tar.gz → 0.7.4__tar.gz

{conformly-0.7.2/src/conformly.egg-info → conformly-0.7.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: conformly
-Version: 0.7.2
+Version: 0.7.4
 Summary: Generate valid & invalid test data from your typed schemas
 Author-email: Nikita Shabanov <nik.shabanov2024@gmail.com>
 License: MIT
@@ -252,6 +252,12 @@ overrides=[
 ]
 ```
 
+Integer seeds, including `0` and negative values, make `case()` and `cases()`
+reproducible for internal generation, including nested models and UUID values.
+The same model, options, and seed produce the same payloads. User-provided default
+factories run once per generated field and must themselves be deterministic;
+the seed does not control their randomness or external state.
+
 ## Error Handling
 
 All `conformly` errors inherit from `ConformlyError`, providing consistent interface for debugging and programmatic handling.
@@ -291,17 +297,43 @@ For `case(Model, valid=False, strategy="<field>")`:
 - **If `allow_structural_violations=True`**, generator may substitute field missing in place of any other violations (avaliable only with `strategy="all"`)
 - **Exactly one field is targeted** (the one specified by `strategy`).
 - **The generator will violate constraints** for that field, making it invalid.
-- **If a field has multiple constraints**, the violated constraint may be chosen by generator logic (not necessarily the one you expect).
+- **Inside collections**, planning selects a compatible dictionary key, value, or
+  element before generation. Fixed tuples retain their length and order; unrelated
+  elements, keys, values, and model fields remain valid.
+- **Only the selected violation is guaranteed on its target**. Other constraints
+  on that same target are not guaranteed to remain satisfied. A `DUPLICATE`
+  violation preserves an allowed collection length; collections with a maximum
+  size below two cannot be targeted for duplication.
+- **Explicit impossible or unsupported violations raise `PlanningError`**;
+  empty-only collections do not offer element violations.
 - **For numeric bounds**, invalid values may violate the lower or upper bound (e.g., `age > 120` or `age < 18`).
 - **For float bounds**, invalid generation may produce `inf` when violating the upper boundary.
 
-If you need **deterministic control** over which exact constraint to violate, that is not implemented in yet (see Roadmap).
+Request an exact violation with `strategy="items::below_min"` or
+`path(Model, lambda m: m.items).violate(V.BELOW_MIN)`. Otherwise, the planner uses
+violation priority and chooses the first compatible key, value, or tuple element.
 
 ## Optional Fields and Defaults
 
-- If a field is **optional** (`Optional[T]`), valid generation may produce `None`.
-- If a field has a **default value**, valid generation returns the default.
-- Invalid generation **requires at least one constraint** on the targeted field (raises `ValueError` otherwise).
+- For untargeted fields, priority is **override → nullable `None` → model default
+  or default factory → generation**. Nullable fields currently always return `None`
+  without an override, even with a non-`None` default; their factories are not called.
+- Model defaults, factory results and overrides are trusted and returned without
+  validation. `valid=True` guarantees the validity of generated values, not of
+  caller-supplied data. An invalid supplied value can also make an unrelated field
+  invalid when generating a negative case.
+- Invalid targets bypass their defaults, nullable priority and overrides. Other
+  fields retain the priority above. Default factories are called once per generated
+  payload when selected by this priority; attrs factories requiring `self` are unsupported.
+- TypedDict `NotRequired[T]` controls key presence independently of whether `T`
+  accepts `None`. Valid generation currently includes these keys with values of `T`;
+  `NotRequired[int]` does not become a present `None`.
+- `MISSING_FIELD` is offered only for required fields: nullable required fields can
+  be removed, but fields with defaults and TypedDict `NotRequired` keys cannot.
+  `EXTRA_FIELD` is offered for Pydantic only with `extra="forbid"`; `ignore` and
+  `allow` accept extra data. Other adapters treat undeclared keys as structural violations.
+- A target needs an applicable semantic, type or structural violation; impossible
+  explicit requests raise `PlanningError`.
 
 ## Constraints
 
@@ -321,6 +353,19 @@ If you need **deterministic control** over which exact constraint to violate, th
 | Collection | `MaxItems(n)` | `max_length=n` (for lists in `Field(...)`) |
 | Collection | `UniqueItems(bool)` | `set[T]`, `frozenset[T]` |
 
+`Pattern` uses Python regex search semantics, consistent with Pydantic: a match
+anywhere in the string is sufficient. Use anchors (`^...$`) to require a whole-string
+match. Pattern mismatches are verified; unsuccessful inversion raises a structured
+`GenerationError` instead of returning a matching value. Obvious universal patterns
+(such as `(?s).*`) are excluded from automatic planning, and explicit mismatch
+requests raise `PlanningError`.
+
+`MultipleOf` requires a finite positive divisor. For floats, a quotient within
+`1e-9` of an integer is treated as a multiple (no relative tolerance). Integer
+`NOT_MULTIPLE` requests for divisors such as `1` or `0.5`, which divide every integer,
+raise `PlanningError` and are excluded from automatic planning. A bounded range
+without a representable multiple raises `GenerationError` with code `no_multiples_of`.
+
 > Important: Pydantic's constr(), conint(), and functional validators are not interpreted as constraints.
 > Use Field() parameters for constraint extraction.
 
@@ -648,7 +693,15 @@ print(trace.generated_value)
 print(trace.seed)
 ```
 
-The trace includes generation metadata such as the target path, generated value, violation type, random seed, and value source.
+Tracing is available for `case(..., valid=False)`. The trace describes the selected
+target: its dotted path, violation, generated value, seed, and value source. This
+applies to DSL and string paths as well as `"first"` and `"random"` selection.
+Unrelated fields, defaults, and overrides do not overwrite target metadata. For
+`MISSING_FIELD`, the value is the internal `UNSET` sentinel because the field is
+absent from the payload.
+
+Enabling tracing leaves payloads, internal RNG consumption, and default factory
+call counts unchanged. A reused tracer describes the latest completed generation.
 
 
 ## Development

{conformly-0.7.2 → conformly-0.7.4}/README.md

@@ -219,6 +219,12 @@ overrides=[
 ]
 ```
 
+Integer seeds, including `0` and negative values, make `case()` and `cases()`
+reproducible for internal generation, including nested models and UUID values.
+The same model, options, and seed produce the same payloads. User-provided default
+factories run once per generated field and must themselves be deterministic;
+the seed does not control their randomness or external state.
+
 ## Error Handling
 
 All `conformly` errors inherit from `ConformlyError`, providing consistent interface for debugging and programmatic handling.
@@ -258,17 +264,43 @@ For `case(Model, valid=False, strategy="<field>")`:
 - **If `allow_structural_violations=True`**, generator may substitute field missing in place of any other violations (avaliable only with `strategy="all"`)
 - **Exactly one field is targeted** (the one specified by `strategy`).
 - **The generator will violate constraints** for that field, making it invalid.
-- **If a field has multiple constraints**, the violated constraint may be chosen by generator logic (not necessarily the one you expect).
+- **Inside collections**, planning selects a compatible dictionary key, value, or
+  element before generation. Fixed tuples retain their length and order; unrelated
+  elements, keys, values, and model fields remain valid.
+- **Only the selected violation is guaranteed on its target**. Other constraints
+  on that same target are not guaranteed to remain satisfied. A `DUPLICATE`
+  violation preserves an allowed collection length; collections with a maximum
+  size below two cannot be targeted for duplication.
+- **Explicit impossible or unsupported violations raise `PlanningError`**;
+  empty-only collections do not offer element violations.
 - **For numeric bounds**, invalid values may violate the lower or upper bound (e.g., `age > 120` or `age < 18`).
 - **For float bounds**, invalid generation may produce `inf` when violating the upper boundary.
 
-If you need **deterministic control** over which exact constraint to violate, that is not implemented in yet (see Roadmap).
+Request an exact violation with `strategy="items::below_min"` or
+`path(Model, lambda m: m.items).violate(V.BELOW_MIN)`. Otherwise, the planner uses
+violation priority and chooses the first compatible key, value, or tuple element.
 
 ## Optional Fields and Defaults
 
-- If a field is **optional** (`Optional[T]`), valid generation may produce `None`.
-- If a field has a **default value**, valid generation returns the default.
-- Invalid generation **requires at least one constraint** on the targeted field (raises `ValueError` otherwise).
+- For untargeted fields, priority is **override → nullable `None` → model default
+  or default factory → generation**. Nullable fields currently always return `None`
+  without an override, even with a non-`None` default; their factories are not called.
+- Model defaults, factory results and overrides are trusted and returned without
+  validation. `valid=True` guarantees the validity of generated values, not of
+  caller-supplied data. An invalid supplied value can also make an unrelated field
+  invalid when generating a negative case.
+- Invalid targets bypass their defaults, nullable priority and overrides. Other
+  fields retain the priority above. Default factories are called once per generated
+  payload when selected by this priority; attrs factories requiring `self` are unsupported.
+- TypedDict `NotRequired[T]` controls key presence independently of whether `T`
+  accepts `None`. Valid generation currently includes these keys with values of `T`;
+  `NotRequired[int]` does not become a present `None`.
+- `MISSING_FIELD` is offered only for required fields: nullable required fields can
+  be removed, but fields with defaults and TypedDict `NotRequired` keys cannot.
+  `EXTRA_FIELD` is offered for Pydantic only with `extra="forbid"`; `ignore` and
+  `allow` accept extra data. Other adapters treat undeclared keys as structural violations.
+- A target needs an applicable semantic, type or structural violation; impossible
+  explicit requests raise `PlanningError`.
 
 ## Constraints
 
@@ -288,6 +320,19 @@ If you need **deterministic control** over which exact constraint to violate, th
 | Collection | `MaxItems(n)` | `max_length=n` (for lists in `Field(...)`) |
 | Collection | `UniqueItems(bool)` | `set[T]`, `frozenset[T]` |
 
+`Pattern` uses Python regex search semantics, consistent with Pydantic: a match
+anywhere in the string is sufficient. Use anchors (`^...$`) to require a whole-string
+match. Pattern mismatches are verified; unsuccessful inversion raises a structured
+`GenerationError` instead of returning a matching value. Obvious universal patterns
+(such as `(?s).*`) are excluded from automatic planning, and explicit mismatch
+requests raise `PlanningError`.
+
+`MultipleOf` requires a finite positive divisor. For floats, a quotient within
+`1e-9` of an integer is treated as a multiple (no relative tolerance). Integer
+`NOT_MULTIPLE` requests for divisors such as `1` or `0.5`, which divide every integer,
+raise `PlanningError` and are excluded from automatic planning. A bounded range
+without a representable multiple raises `GenerationError` with code `no_multiples_of`.
+
 > Important: Pydantic's constr(), conint(), and functional validators are not interpreted as constraints.
 > Use Field() parameters for constraint extraction.
 
@@ -615,7 +660,15 @@ print(trace.generated_value)
 print(trace.seed)
 ```
 
-The trace includes generation metadata such as the target path, generated value, violation type, random seed, and value source.
+Tracing is available for `case(..., valid=False)`. The trace describes the selected
+target: its dotted path, violation, generated value, seed, and value source. This
+applies to DSL and string paths as well as `"first"` and `"random"` selection.
+Unrelated fields, defaults, and overrides do not overwrite target metadata. For
+`MISSING_FIELD`, the value is the internal `UNSET` sentinel because the field is
+absent from the payload.
+
+Enabling tracing leaves payloads, internal RNG consumption, and default factory
+call counts unchanged. A reused tracer describes the latest completed generation.
 
 
 ## Development

{conformly-0.7.2 → conformly-0.7.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "conformly"
-version = "0.7.2"
+version = "0.7.4"
 description = "Generate valid & invalid test data from your typed schemas"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -90,6 +90,7 @@ line-ending = "auto"
 
 
 [tool.pytest.ini_options]
+xfail_strict = true
 markers = ["benchmark: performance benchmarks"]
 
 addopts = ["-v", "--strict-markers"]

{conformly-0.7.2 → conformly-0.7.4}/src/conformly/_internal/api/_utils.py

@@ -62,7 +62,13 @@ def plan_tasks(
 
     if split_by_violations:
         return [
-            PlannedTask(path=path, allowed_violations=(violation,))
+            plan_violation_task(
+                model,
+                path,
+                allow_type_mismatch,
+                allow_structural_violations,
+                forced_violation=violation,
+            )
             for path in paths
             for violation in plan_violation_task(
                 model, path, allow_type_mismatch, allow_structural_violations

{conformly-0.7.2 → conformly-0.7.4}/src/conformly/_internal/api/case.py

@@ -38,9 +38,11 @@ def case(
             If False, generate an invalid one.
 
         seed:
-            Random seed for reproducible generation.
+            Random seed for reproducible internal generation.
             - `None` (default): Use system randomness (different output each run).
-            - `int`: Initialize RNG with fixed seed (same output for same seed).
+            - `int`: Initialize RNG with a fixed seed, including 0 and negatives.
+            User-provided default factories must be deterministic for identical
+            payloads; their randomness is not controlled by this seed.
 
         strategy:
             Define which field to violate when valid=False.
@@ -63,14 +65,17 @@ def case(
 
         overrides:
             Optional list of `PathSelector` to set field values.
-            - Applied after generation
-            - Override generated values
+            - Used instead of generated values and model defaults
             - With valid=False: act as defaults (ignored if field is violated)
 
         allow_type_mismatch:
             If True fields could be type mismatched.
             Availiable only when valid=False.
 
+        tracer:
+            Optional tracer for invalid generation. Records the selected target
+            path, violation, and value without changing generation or factory calls.
+
     Returns:
         A dictionary representing the instance.
     """
@@ -111,9 +116,6 @@ def case(
             strategy=strategy,
         )
 
-    if tracer and isinstance(strategy, PathSelector):
-        tracer.set_target_path(strategy.raw_path)
-
     task = plan_tasks(
         model,
         ctx=ctx,

{conformly-0.7.2 → conformly-0.7.4}/src/conformly/_internal/api/cases.py

@@ -38,9 +38,11 @@ def cases(
             If False, generate invalid ones.
 
         seed:
-            Random seed for reproducible generation.
+            Random seed for reproducible internal generation.
             - `None` (default): Use system randomness (different output each run).
-            - `int`: Initialize RNG with fixed seed (same output for same seed).
+            - `int`: Initialize RNG with a fixed seed, including 0 and negatives.
+            User-provided default factories must be deterministic for identical
+            payloads; their randomness is not controlled by this seed.
 
         strategy:
             Define how fields are selected for violation when valid=False.
@@ -74,8 +76,7 @@ def cases(
 
         overrides:
             Optional list of `PathSelector` to set field values.
-            - Applied after generation
-            - Override generated values
+            - Used instead of generated values and model defaults
             - With valid=False: act as defaults (ignored if field is violated)
 
 

{conformly-0.7.2 → conformly-0.7.4}/src/conformly/_internal/generator/context.py

@@ -12,5 +12,5 @@ class GenerationContext:
 
 
 def create_context(seed: int | None = None) -> GenerationContext:
-    rng = random.Random(seed) if seed else random.Random()
+    rng = random.Random(seed)
     return GenerationContext(rng=rng, rstr=Rstr(rng), seed=seed)

{conformly-0.7.2 → conformly-0.7.4}/src/conformly/_internal/generator/orchestration.py

@@ -5,12 +5,19 @@ from .context import GenerationContext
 from .registry import choose_mismatch_kind, get_generator
 
 from conformly._internal.planner import PlannedTask
+from conformly._internal.planner.model import CollectionTarget
 from conformly._internal.resolver import (
     ResolvedField,
     ResolvedModel,
     create_minimal_semantic,
 )
-from conformly._internal.resolver.semantics import ListSemantic, TupleSemantic
+from conformly._internal.resolver.semantics import (
+    DictSemantic,
+    FieldSemantics,
+    ListSemantic,
+    ObjectSemantic,
+    TupleSemantic,
+)
 from conformly._internal.tracer import Tracer, ValueSource
 from conformly._internal.types import UNSET, FieldKind, FieldPath, ViolationType
 
@@ -43,6 +50,8 @@ def generate_invalid(
         violations=task.allowed_violations,
         overrides=overrides,
         tracer=tracer,
+        collection_target=task.collection_target,
+        collection_steps=task.collection_steps,
     )
 
 
@@ -54,6 +63,9 @@ def _built_dict_with_violations(
     violations: tuple[ViolationType, ...],
     overrides: dict[FieldPath, Any] | None = None,
     tracer: Tracer | None = None,
+    path_names: tuple[str, ...] = (),
+    collection_target: CollectionTarget | None = None,
+    collection_steps: tuple[tuple[FieldPath, CollectionTarget], ...] = (),
 ) -> dict[str, Any]:
     result: dict[str, Any] = {}
     target_index = target_path[depth]
@@ -72,7 +84,7 @@ def _built_dict_with_violations(
 
     for i in range(0, target_index):
         field = fields[i]
-        result[field.name] = generate_field(ctx, field, None, overrides, tracer)
+        result[field.name] = generate_field(ctx, field, None, overrides)
 
     if target_index < total_fields:
         field = fields[target_index]
@@ -85,7 +97,11 @@ def _built_dict_with_violations(
                     field=field.name,
                 )
 
-            value = generate_field(ctx, field, violations, overrides, tracer)
+            if tracer:
+                tracer.set_target_path(".".join((*path_names, field.name)))
+            value = generate_field(
+                ctx, field, violations, overrides, tracer, collection_target
+            )
             if value is not UNSET:
                 result[field.name] = value
 
@@ -97,7 +113,7 @@ def _built_dict_with_violations(
                     field=field.name,
                 )
 
-            result[field.name] = _built_dict_with_violations(
+            nested_value = _built_dict_with_violations(
                 ctx=ctx,
                 model=field.nested_model,
                 target_path=target_path,
@@ -105,18 +121,44 @@ def _built_dict_with_violations(
                 violations=violations,
                 overrides=overrides,
                 tracer=tracer,
+                path_names=(*path_names, field.name),
+                collection_target=collection_target,
+                collection_steps=collection_steps,
             )
 
-    else:
-        for i, field in enumerate(fields):
-            result[field.name] = generate_field(ctx, field, tracer=tracer)
+            if isinstance(field.semantic, (ListSemantic, DictSemantic)):
+                step = next(
+                    (t for p, t in collection_steps if p == target_path[: depth + 1]),
+                    None,
+                )
+                if step is None:
+                    raise generation_error(
+                        "Nested collection requires a planned target",
+                        code="missing_collection_target",
+                    )
+                container = _generate_nested_collection(
+                    ctx, field.semantic, step, nested_value
+                )
+                result[field.name] = container
+            else:
+                result[field.name] = nested_value
 
+    else:
         key, value = _generate_extra_field_value(ctx)
+        suffix = 1
+        while key in result:
+            key = f"extra_{suffix}"
+            suffix += 1
         result[key] = value
+        if tracer:
+            tracer.set_target_path(".".join((*path_names, key)))
+            tracer.set_violation(ViolationType.EXTRA_FIELD)
+            tracer.set_value_source(ValueSource.GENERATED)
+            tracer.set_generated_value(value)
 
     for i in range(target_index + 1, total_fields):
         field = fields[i]
-        result[field.name] = generate_field(ctx, field, tracer=tracer)
+        result[field.name] = generate_field(ctx, field, overrides=overrides)
 
     return result
 
@@ -127,6 +169,7 @@ def generate_field(
     violations: tuple[ViolationType, ...] | None = None,
     overrides: dict[FieldPath, Any] | None = None,
     tracer: Tracer | None = None,
+    collection_target: CollectionTarget | None = None,
 ) -> Any:
     if violations is None:
         if overrides and field.path in overrides:
@@ -144,18 +187,13 @@ def generate_field(
                 tracer.set_value_source(ValueSource.MODEL_DEFAULT)
 
             default = field.default
-            if callable(default):
-                if tracer:
-                    tracer.set_generated_value(default())
-                return default()
-
+            value = default() if callable(default) else default
             if tracer:
-                tracer.set_generated_value(default())
-
-            return default
+                tracer.set_generated_value(value)
+            return value
 
         if field.nested_model and not isinstance(
-            field.semantic, (ListSemantic, TupleSemantic)
+            field.semantic, (ListSemantic, DictSemantic, TupleSemantic)
         ):
             return generate_valid(ctx, field.nested_model, overrides)
 
@@ -165,31 +203,50 @@ def generate_field(
         tracer.set_violation(violation)
         tracer.set_value_source(ValueSource.GENERATED)
 
-    if violation == ViolationType.TYPE_MISMATCH:
-        mismatch_kind = choose_mismatch_kind(field.semantic.kind)
-        mismatch_semantic = create_minimal_semantic(mismatch_kind)
-        value = get_generator(mismatch_kind).generate_value(
-            ctx, mismatch_semantic, None
-        )
-        if tracer:
-            tracer.set_generated_value(value)
-        return value
-
-    if violation == ViolationType.MISSING_FIELD:
-        if tracer:
-            tracer.set_generated_value(UNSET)
-        return UNSET
-
-    value = get_generator(field.semantic.kind).generate_value(
-        ctx, field.semantic, violation
+    value = generate_semantic_value(
+        ctx, field.semantic, field.nested_model, violations, collection_target
     )
-
     if tracer:
         tracer.set_generated_value(value)
-
     return value
 
 
+def generate_semantic_value(
+    ctx: GenerationContext,
+    semantic: FieldSemantics,
+    nested_model: ResolvedModel | None,
+    violations: tuple[ViolationType, ...] | None,
+    collection_target: CollectionTarget | None = None,
+) -> Any:
+    """Generate directly from resolved semantics, without synthetic field models."""
+    violation = _choose_violation(violations)
+    if violation == ViolationType.TYPE_MISMATCH:
+        mismatch_kind = choose_mismatch_kind(semantic.kind)
+        return get_generator(mismatch_kind).generate_value(
+            ctx, create_minimal_semantic(mismatch_kind), None
+        )
+    if violation == ViolationType.MISSING_FIELD:
+        return UNSET
+    if nested_model is not None and isinstance(semantic, ObjectSemantic):
+        if violation is not None:
+            raise generation_error(
+                "Nested model violation requires a field target",
+                code="missing_nested_target",
+            )
+        return generate_valid(ctx, nested_model)
+    from .types import dictionaries, list as lists, tuple as tuples
+
+    if isinstance(semantic, ListSemantic):
+        return lists.generate_value(ctx, semantic, violation, target=collection_target)
+    if isinstance(semantic, DictSemantic):
+        return dictionaries.generate_value(
+            ctx, semantic, violation, target=collection_target
+        )
+    if isinstance(semantic, TupleSemantic):
+        return tuples.generate_value(ctx, semantic, violation, target=collection_target)
+    return get_generator(semantic.kind).generate_value(ctx, semantic, violation)
+
+
 def _choose_violation(
     violations: tuple[ViolationType, ...] | None,
 ) -> ViolationType | None:
@@ -204,3 +261,28 @@ def _generate_extra_field_value(ctx: GenerationContext) -> tuple[str, Any]:
     value = get_generator(semantic.kind).generate_value(ctx, semantic, None)
     key = "extra"
     return (key, value)
+
+
+def _generate_nested_collection(
+    ctx: GenerationContext,
+    semantic: ListSemantic | DictSemantic,
+    target: CollectionTarget,
+    nested_value: dict[str, Any],
+) -> Any:
+    from .types._utils import calculate_valid_collection_range, unique_collection_range
+    from .types.dictionaries import _generate_dict_of_length
+    from .types.list import _generate_list_of_length
+
+    lower, upper = calculate_valid_collection_range(semantic)
+    if isinstance(semantic, DictSemantic):
+        lower, upper = unique_collection_range(
+            lower, upper, semantic.key_semantic, collection="dict"
+        )
+        length = ctx.rng.randint(lower, upper)
+        return _generate_dict_of_length(
+            ctx, semantic, length, target=target, target_value=nested_value
+        )
+    length = ctx.rng.randint(lower, upper)
+    result = _generate_list_of_length(ctx, semantic, length - 1)
+    result.insert(target.index, nested_value)
+    return result

conformly-0.7.4/src/conformly/_internal/generator/types/_utils.py

@@ -0,0 +1,84 @@
+from typing import Any
+
+from .._errors import generation_error
+from ..context import GenerationContext
+
+from conformly._internal.resolver import ResolvedModel
+from conformly._internal.resolver.semantics import (
+    DictSemantic,
+    FieldSemantics,
+    ListSemantic,
+    TupleSemantic,
+)
+from conformly._internal.resolver.semantics._domains import finite_cardinality
+from conformly._internal.types import ViolationType
+from conformly.exceptions import GenerationError
+
+
+def calculate_valid_collection_range(
+    semantic: ListSemantic | DictSemantic | TupleSemantic,
+) -> tuple[int, int]:
+    """Choose a small default range without overriding declared size limits."""
+    if semantic.length_range is None:
+        return 1, 3
+    lower = semantic.length_range.min_length
+    upper = semantic.length_range.max_length
+    if upper == 0:
+        return lower, 0
+    lower = max(1, lower)
+    return lower, upper if upper is not None else max(3, lower)
+
+
+def unique_collection_range(
+    lower: int,
+    upper: int,
+    semantic: FieldSemantics,
+    *,
+    collection: str,
+    extra_values: int = 0,
+) -> tuple[int, int]:
+    cardinality = finite_cardinality(semantic)
+    if cardinality is not None:
+        cardinality += extra_values
+        if lower > cardinality:
+            raise generation_error(
+                "Collection size exceeds the number of distinct valid values",
+                code="impossible_collection_size",
+                collection=collection,
+                requested_size=lower,
+                cardinality=cardinality,
+            )
+        upper = min(upper, cardinality)
+    return lower, upper
+
+
+def collection_retry_error(
+    *, collection: str, requested_size: int, generated_size: int, attempts: int
+) -> GenerationError:
+    return generation_error(
+        "Could not fill collection with distinct valid values",
+        code="collection_retry_exhausted",
+        collection=collection,
+        requested_size=requested_size,
+        generated_size=generated_size,
+        attempts=attempts,
+    )
+
+
+def is_hashable(value: Any) -> bool:
+    try:
+        hash(value)
+        return True
+    except TypeError:
+        return False
+
+
+def generate_collection_item(
+    ctx: GenerationContext,
+    item_semantic: FieldSemantics,
+    item_nested_model: ResolvedModel | None,
+    violations: tuple[ViolationType, ...] | None,
+) -> Any:
+    from ..orchestration import generate_semantic_value
+
+    return generate_semantic_value(ctx, item_semantic, item_nested_model, violations)