overture-schema-codegen 0.1.1.dev0__py3-none-any.whl

overture/schema/codegen/pyspark/test_data/constraint_values.py

@@ -0,0 +1,203 @@
+"""Paired valid/invalid value generation for string-constraint and numeric-bound checks.
+
+Each entry in `CONSTRAINT_VALUES` carries both sides of the pair:
+`valid` is accepted by the constraint; `invalid` violates it.
+Both sides are mandatory — partial entries are not allowed.
+
+Consumed by `base_row` (uses the `valid` side to produce valid base rows)
+and `invalid_value` (uses the `invalid` side to produce scenario mutations).
+
+`valid_bound` and `invalid_bound` are analogous functions for numeric
+bound descriptors, placed here so both sides of every constraint kind
+live in one module.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from overture.schema.system.field_constraint.string import (
+    CountryCodeAlpha2Constraint,
+    HexColorConstraint,
+    JsonPointerConstraint,
+    LanguageTagConstraint,
+    NoWhitespaceConstraint,
+    PhoneNumberConstraint,
+    RegionCodeConstraint,
+    SnakeCaseConstraint,
+    StrippedConstraint,
+    WikidataIdConstraint,
+)
+
+from ..constraint_dispatch import ExpressionDescriptor, normalize_anchor
+
+__all__ = [
+    "CONSTRAINT_VALUES",
+    "PATTERN_VALUES",
+    "ConstraintValues",
+    "curated_pattern_values",
+    "invalid_bound",
+    "uncurated_pattern_error",
+    "valid_bound",
+]
+
+
+@dataclass(frozen=True, slots=True)
+class ConstraintValues:
+    """A paired valid/invalid value for one constraint type."""
+
+    valid: object
+    invalid: object
+
+
+CONSTRAINT_VALUES: dict[type, ConstraintValues] = {
+    CountryCodeAlpha2Constraint: ConstraintValues(valid="US", invalid="99"),
+    HexColorConstraint: ConstraintValues(valid="#aabbcc", invalid="not-hex"),
+    JsonPointerConstraint: ConstraintValues(valid="/valid/pointer", invalid="no-slash"),
+    LanguageTagConstraint: ConstraintValues(valid="en", invalid="123"),
+    NoWhitespaceConstraint: ConstraintValues(
+        valid="nowhitespace", invalid="has whitespace"
+    ),
+    PhoneNumberConstraint: ConstraintValues(
+        valid="+1 555-555-5555", invalid="1234567890"
+    ),
+    RegionCodeConstraint: ConstraintValues(valid="US-CA", invalid="99-999"),
+    SnakeCaseConstraint: ConstraintValues(valid="snake_case", invalid="HAS SPACES"),
+    StrippedConstraint: ConstraintValues(valid="clean", invalid=" has spaces "),
+    WikidataIdConstraint: ConstraintValues(valid="Q42", invalid="P999"),
+}
+
+
+# Curated valid/invalid pairs for fields whose only string constraint is a
+# raw pydantic `Field(pattern=...)` (a `_PydanticGeneralMetadata`, not a
+# schema constraint class -- so it has no `CONSTRAINT_VALUES` type key).
+# Keyed by the anchor-normalized pattern that lands in the generated
+# `check_pattern` descriptor's `args`, so both `base_row` and
+# `invalid_value` look it up via `desc.args[0]`. An uncurated raw pattern
+# fails loud on both sides rather than guessing a value.
+#
+# Generation-principle gap: this table is hand-maintained and keyed by the
+# literal regex, so it drifts from the schema -- a renamed or retuned
+# `Field(pattern=)` silently loses its entry until the next regeneration
+# fails loud. The principled fix is to derive both sides from the regex
+# itself (e.g. a matching/non-matching string generator), removing the
+# hand-keyed table entirely. Out of scope here; tracked separately.
+PATTERN_VALUES: dict[str, ConstraintValues] = {
+    # Sources.license_priority key (LicenseShortname): `^[A-Za-z0-9._+\-]+$`.
+    normalize_anchor(r"^[A-Za-z0-9._+\-]+$"): ConstraintValues(
+        valid="ODbL-1.0", invalid="bad license!"
+    ),
+}
+
+
+def curated_pattern_values(desc: ExpressionDescriptor) -> ConstraintValues | None:
+    """Curated valid/invalid pair for a raw-pattern `check_pattern` descriptor.
+
+    The pattern key is the descriptor's first arg (the anchor-normalized
+    regex). Returns None when the pattern is not curated in `PATTERN_VALUES`
+    -- named constraints resolve via `CONSTRAINT_VALUES` instead, and an
+    uncurated raw pattern has no values.
+    """
+    pattern = desc.args[0] if desc.args else None
+    if isinstance(pattern, str):
+        return PATTERN_VALUES.get(pattern)
+    return None
+
+
+def uncurated_pattern_error(desc: ExpressionDescriptor, *, side: str) -> ValueError:
+    """Build the error for a `check_pattern` descriptor with no curated value.
+
+    Raised symmetrically by `base_row` (valid side) and `invalid_value`
+    (invalid side) when a raw `Field(pattern=)` has no `PATTERN_VALUES`
+    entry: both name the table to update rather than guessing a value.
+
+    Parameters
+    ----------
+    desc
+        The uncurated `check_pattern` descriptor.
+    side
+        Which value could not be produced -- `"valid"` or `"invalid"`.
+    """
+    return ValueError(
+        f"No {side} value defined for check_pattern with "
+        f"constraint_type={desc.constraint_type!r}, pattern={desc.args!r}. "
+        "Add an entry to CONSTRAINT_VALUES (named constraint) or "
+        "PATTERN_VALUES (raw pydantic pattern) in constraint_values.py."
+    )
+
+
+def valid_bound(desc: ExpressionDescriptor) -> object:
+    """Produce a value satisfying a bounds check for base row generation.
+
+    Prefers inclusive boundaries: if `ge` is present it is already a valid
+    value; if `le` is present and `ge` is absent, `le` is valid. When only
+    exclusive bounds remain, a strictly-interior value is computed: midpoint
+    for both-exclusive, or a type-aware step away from a single bound.
+
+    Parameters
+    ----------
+    desc
+        A `check_bounds` descriptor with at least one bound kwarg.
+
+    Returns
+    -------
+    object
+        A value on the valid side of all bounds. Falls back to `0` when
+        no recognised bound key is present.
+    """
+    kwargs = dict(desc.kwargs)
+    if "ge" in kwargs:
+        return kwargs["ge"]
+    if "le" in kwargs:
+        return kwargs["le"]
+    gt = kwargs.get("gt")
+    lt = kwargs.get("lt")
+    if gt is not None and lt is not None:
+        # Midpoint: integer midpoint for int bounds, float midpoint for float.
+        if isinstance(gt, float) or isinstance(lt, float):
+            return (float(gt) + float(lt)) / 2.0  # type: ignore[arg-type,operator]
+        mid = (gt + lt) // 2  # type: ignore[operator]
+        if not (gt < mid < lt):  # type: ignore[operator]
+            raise ValueError(
+                f"No valid integer strictly between gt={gt!r} and lt={lt!r}"
+            )
+        return mid
+    if gt is not None:
+        step: object = 1.0 if isinstance(gt, float) else 1
+        return gt + step  # type: ignore[operator]
+    if lt is not None:
+        step = 1.0 if isinstance(lt, float) else 1
+        return lt - step  # type: ignore[operator]
+    return 0
+
+
+def invalid_bound(desc: ExpressionDescriptor) -> object:
+    """Produce a value violating a bounds check for invalid-value generation.
+
+    The `ge` / `le` branches return one below / above the bound. For
+    `ge=0` this returns `-1`, which violates the bound but would also
+    underflow an unsigned base type. No schema today combines `ge=0` with
+    an unsigned terminal -- if that ever changes, the caller will need to
+    consult the base type and pick a sentinel (e.g. a string or null) for
+    the violating value.
+
+    Parameters
+    ----------
+    desc
+        A `check_bounds` descriptor with at least one bound kwarg.
+
+    Raises
+    ------
+    ValueError
+        When no recognised bound key is found.
+    """
+    kwargs = dict(desc.kwargs)
+    if "ge" in kwargs:
+        return kwargs["ge"] - 1  # type: ignore[operator]
+    if "gt" in kwargs:
+        return kwargs["gt"]
+    if "le" in kwargs:
+        return kwargs["le"] + 1  # type: ignore[operator]
+    if "lt" in kwargs:
+        return kwargs["lt"]
+    raise ValueError(f"No recognised bound key in kwargs: {kwargs!r}")

overture/schema/codegen/pyspark/test_data/invalid_value.py

@@ -0,0 +1,105 @@
+"""Generate constraint-violating values for the rendered conformance tests.
+
+`invalid_value` returns a concrete value that violates a given check. The
+generated tests inject these into otherwise-valid rows to confirm that
+each constraint produces the expected violation.
+"""
+
+from __future__ import annotations
+
+from overture.schema.system.geometric.geom import GeometryType
+
+from ..constraint_dispatch import ExpressionDescriptor
+from .constraint_values import (
+    CONSTRAINT_VALUES,
+    curated_pattern_values,
+    invalid_bound,
+    uncurated_pattern_error,
+)
+
+__all__ = ["invalid_value"]
+
+# Ordered candidates for the invalid geometry side (first not in allowed set wins)
+_INVALID_GEOMETRY_CANDIDATES: tuple[tuple[GeometryType, str], ...] = (
+    (GeometryType.POINT, "POINT (0 0)"),
+    (GeometryType.LINE_STRING, "LINESTRING (0 0, 1 1)"),
+    (GeometryType.GEOMETRY_COLLECTION, "GEOMETRYCOLLECTION EMPTY"),
+)
+
+
+# Direct lookup: check function name -> invalid value (no descriptor inspection).
+# Reserved for checks with no associated constraint type (url/email, linear_range,
+# bbox, required, enum, and min-length literals).
+_INVALID_LITERALS: dict[str, object] = {
+    "check_required": None,
+    "check_enum": "__INVALID__",
+    "check_url_format": "not-a-url",
+    "check_url_length": "https://" + "x" * 2076,
+    "check_email": "not-an-email",
+    "check_array_min_length": [],
+    "check_string_min_length": "",
+    "check_linear_range_length": [0.5],
+    "check_linear_range_bounds": [1.5, 2.0],
+    "check_linear_range_order": [0.8, 0.2],
+    "check_bbox_completeness": {"xmin": 0.0, "xmax": 1.0, "ymin": None, "ymax": 1.0},
+}
+
+
+def invalid_value(desc: ExpressionDescriptor) -> object:
+    """Return a Python value that violates `desc`'s check function.
+
+    Parameters
+    ----------
+    desc
+        The expression descriptor to produce an invalid value for.
+
+    Raises
+    ------
+    ValueError
+        For unrecognised check function names, unknown `constraint_type`
+        on `check_pattern` descriptors, or when all geometry candidates
+        are in the allowed set.
+    """
+    fn = desc.function
+    # Constraint-type lookup precedes function-name lookup: any type present in
+    # CONSTRAINT_VALUES resolves via the table even when its check function also
+    # appears in _INVALID_LITERALS (e.g. check_stripped, check_json_pointer).
+    if desc.constraint_type in CONSTRAINT_VALUES:
+        return CONSTRAINT_VALUES[desc.constraint_type].invalid
+    if fn in _INVALID_LITERALS:
+        return _INVALID_LITERALS[fn]
+    if fn == "check_bounds":
+        return invalid_bound(desc)
+    if fn == "check_multiple_of":
+        # A non-multiple of the divisor: `divisor * 1.5` leaves a remainder of
+        # `divisor / 2`. For divisor=1 this is 1.5, kept inside a typical
+        # [1, N] bound range so a co-located bounds check does not also fire
+        # and the scenario isolates the multiple-of check. Isolation is a
+        # convenience, not a requirement: the harness asserts the expected
+        # check is among those raised, so an extra bounds violation is
+        # tolerated.
+        return float(desc.args[0]) * 1.5  # type: ignore[arg-type]
+    if fn == "check_pattern":
+        if (curated := curated_pattern_values(desc)) is not None:
+            return curated.invalid
+        raise uncurated_pattern_error(desc, side="invalid")
+    if fn == "check_array_max_length":
+        max_len = int(desc.args[0])  # type: ignore[call-overload]
+        return [{}] * (max_len + 1)
+    if fn == "check_string_max_length":
+        max_len = int(desc.args[0])  # type: ignore[call-overload]
+        return "x" * (max_len + 1)
+    if fn == "check_geometry_type":
+        return _invalid_geometry(desc)
+    raise ValueError(f"No invalid value defined for check function: {fn!r}")
+
+
+def _invalid_geometry(desc: ExpressionDescriptor) -> str:
+    allowed = set(desc.args)
+    for geom_type, wkt in _INVALID_GEOMETRY_CANDIDATES:
+        if geom_type not in allowed:
+            return wkt
+    raise ValueError(
+        f"All geometry candidates are in the allowed set: {allowed!r}. "
+        "Cannot produce an invalid geometry value."
+    )

overture/schema/codegen/pyspark/test_data/scaffold.py

@@ -0,0 +1,390 @@
+"""Generate sparse path scaffolds for the rendered conformance tests.
+
+`generate_scaffold` builds a sparse dict that, when merged with a base
+row, supplies the nested intermediates (optional structs, arrays) the
+base row lacks but a check's field path requires.
+`generate_model_scaffold` does the same for model-level constraints.
+`leaf_list_depth` reports unaccounted-for list depth on a target field.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from overture.schema.system.field_path import (
+    ArraySegment,
+    FieldPath,
+    FieldSegment,
+    Iterated,
+    MapSegment,
+    terminal_run_start,
+)
+
+from ...extraction.field_walk import (
+    has_array_layer,
+    list_depth,
+    terminal_model_ref,
+    terminal_union_ref,
+)
+from ...extraction.specs import FieldSpec, ModelSpec, RecordSpec
+from ..check_ir import (
+    Check,
+    ElementGuard,
+    ModelCheck,
+)
+from .base_row import (
+    condition_overrides_for_present_field,
+    generate_base_row,
+    resolve_arm_spec,
+    value_for_field,
+)
+
+__all__ = [
+    "generate_model_scaffold",
+    "generate_scaffold",
+    "leaf_list_depth",
+]
+
+# Sentinel for "no leaf override": the terminal field keeps its synthesized
+# value. A `None` / `""` leaf override is meaningful, so it cannot be the
+# default.
+_UNSET: object = object()
+
+
+def _nest_leaf_value(value: object, field_spec: FieldSpec) -> object:
+    """Wrap a scalar leaf override to the field's list nesting depth.
+
+    `value_for_field` returns a list for a list-typed field, so a bare scalar
+    override (e.g. a literal alternative) is wrapped to the same depth: `[v]`
+    for `list[T]`, `[[v]]` for `list[list[T]]`, and `v` for a scalar field.
+    """
+    for _ in range(list_depth(field_spec.shape)):
+        value = [value]
+    return value
+
+
+@dataclass(frozen=True, slots=True)
+class _ElementDiscriminator:
+    """Discriminator value to seed at one nesting depth of the scaffold."""
+
+    field: str
+    value: str
+    depth: int
+
+
+def _is_anonymous_iter(seg: FieldSegment) -> bool:
+    """Return True when *seg* iterates a container nested directly inside another.
+
+    In a run of nested containers the first takes the field's name; each
+    further level is *anonymous*, because no field name introduces it -- the
+    parent element is itself the next container. For `grid: list[list[int]]`
+    the path `grid[][]` is a named `ArraySegment("grid")` followed by an
+    anonymous `ArraySegment("")`; this returns False for the first and True
+    for the second, the "extra" iteration past the named `grid`.
+    """
+    return isinstance(seg, (ArraySegment, MapSegment)) and seg.is_anonymous
+
+
+def _find_field_spec(fields: list[FieldSpec], name: str) -> FieldSpec | None:
+    """Find a FieldSpec by name in a list."""
+    for f in fields:
+        if f.name == name:
+            return f
+    return None
+
+
+def leaf_list_depth(field_path: FieldPath, spec: ModelSpec) -> int:
+    """Return the unaccounted-for list depth of the leaf field.
+
+    Walks the spec's field tree along *field_path* and returns the leaf's
+    `list_depth(shape)` minus the path's own trailing iteration depth at
+    the leaf. The leaf is the last *named* segment -- any anonymous
+    `ArraySegment`s after it are further list-nesting of that same field,
+    not a lookup of their own, and are skipped both when descending the
+    field tree and when counting how much depth the path already covers.
+    Paths whose terminal segment is itself an array target the array's
+    elements, so the mutation already operates one level deep. Returns 0
+    when *field_path* is empty or when any segment fails to resolve
+    against *spec* (e.g. union arms that don't share the path's
+    intermediate fields).
+    """
+    segments = field_path.segments
+    if not segments:
+        return 0
+
+    leaf_index = terminal_run_start(segments)
+    leaf_seg = segments[leaf_index]
+    terminal_iter = (
+        (len(segments) - leaf_index) if isinstance(leaf_seg, ArraySegment) else 0
+    )
+
+    fields = list(spec.fields)
+    for seg in segments[:leaf_index]:
+        if isinstance(seg, ArraySegment) and seg.is_anonymous:
+            continue
+        field = _find_field_spec(fields, seg.name)
+        if field is None:
+            return 0
+        model_ref = terminal_model_ref(field.shape)
+        if model_ref is None:
+            return 0
+        fields = model_ref.model.fields
+
+    leaf = _find_field_spec(fields, leaf_seg.name)
+    if leaf is None:
+        return 0
+    return max(0, list_depth(leaf.shape) - terminal_iter)
+
+
+def _child_container_spec(
+    field_spec: FieldSpec, discriminator_value: object | None
+) -> RecordSpec | None:
+    """Resolve the model a path field descends into.
+
+    Returns the field's terminal `ModelRef` model, or -- for a discriminated
+    union -- the member arm the `discriminator_value` selects (the first
+    member when the check is not arm-gated). `None` when the field has neither
+    a model nor a union terminal.
+    """
+    model_ref = terminal_model_ref(field_spec.shape)
+    if model_ref is not None:
+        return model_ref.model
+    union_ref = terminal_union_ref(field_spec.shape)
+    if union_ref is not None:
+        return resolve_arm_spec(union_ref.union, discriminator_value)
+    return None
+
+
+def _walk_to_target(
+    segments: tuple[FieldSegment, ...],
+    fields: list[FieldSpec],
+    spec_name: str,
+    *,
+    discriminator: _ElementDiscriminator | None,
+    current_depth: int = 0,
+    leaf_value: object = _UNSET,
+) -> dict[str, Any]:
+    """Recursively build a constraint-satisfying scaffold along the path.
+
+    Each container model on the path is built as a valid base row
+    (`generate_base_row` -- required fields populated and model constraints
+    such as `require_any_of` satisfied), then the on-path child overrides its
+    field. A discriminated-union element resolves to the arm the seeded
+    discriminator selects (or the first member when the check is not
+    arm-gated), so the element is a valid instance of a concrete arm rather
+    than an untagged `{}`.
+
+    Accepts any `FieldSegment`: struct steps recurse, an `ArraySegment`
+    wraps its inner value in lists, and a trailing `MapSegment` resolves
+    via `value_for_field` (which populates the map with a valid entry),
+    so a map-projection target scaffolds the same way as a struct terminal.
+
+    `leaf_value`, when set, replaces the synthesized value at the terminal
+    field -- used to seed a specific valid value (e.g. a literal alternative)
+    at the check's target.
+    """
+    if not segments:
+        return {}
+
+    seg = segments[0]
+    remaining = segments[1:]
+    field_spec = _find_field_spec(fields, seg.name)
+
+    # A path segment that resolves to no field, or that tries to descend into a
+    # non-container, would leave the scaffold short of its target -- the
+    # `::valid` row would then assert nothing (the vacuous-valid-row bug this
+    # generator exists to prevent). Fail loud at generation time instead.
+    if field_spec is None:
+        raise ValueError(
+            f"scaffold path segment {seg.name!r} matches no field "
+            f"(available: {sorted(f.name for f in fields)})"
+        )
+
+    # Anonymous iterating segments immediately after `seg` are further
+    # container-nesting of THIS SAME field (`list[list[...]]`,
+    # `dict[K, dict[K2, ...]]`, no intervening field name), not separate
+    # lookups -- `generate_base_row`/`value_for_field` resolve straight
+    # through every list and map layer, so peeling the run here (rather than
+    # recursing anonymous-segment-by-segment) keeps the base-row merge below
+    # anchored on the field `seg` actually names. `extra_iter` carries only the
+    # ARRAY levels to the wrap step; anonymous map levels need no manual
+    # wrapping, since `value_for_field` nests the map itself.
+    extra_iter = 0
+    while remaining and _is_anonymous_iter(remaining[0]):
+        if isinstance(remaining[0], ArraySegment):
+            extra_iter += 1
+        remaining = remaining[1:]
+
+    inner: Any
+    if remaining:
+        discriminator_value = (
+            discriminator.value
+            if discriminator is not None and current_depth == discriminator.depth
+            else None
+        )
+        child_spec = _child_container_spec(field_spec, discriminator_value)
+        if child_spec is None:
+            raise ValueError(
+                f"scaffold cannot descend into non-container field {seg.name!r} "
+                f"with path remaining {[s.name for s in remaining]!r}"
+            )
+        recursed = _walk_to_target(
+            remaining,
+            child_spec.fields,
+            spec_name,
+            discriminator=discriminator,
+            current_depth=current_depth + 1 + extra_iter,
+            leaf_value=leaf_value,
+        )
+        inner = {**generate_base_row(child_spec), **recursed}
+    elif leaf_value is not _UNSET:
+        inner = _nest_leaf_value(leaf_value, field_spec)
+    else:
+        inner = value_for_field(field_spec, spec_name)
+
+    if (
+        isinstance(inner, dict)
+        and discriminator is not None
+        and current_depth == discriminator.depth
+    ):
+        inner[discriminator.field] = discriminator.value
+
+    # When the terminal segment is an array and the field itself is a list,
+    # `value_for_field` already wrapped the value -- skip extra wrapping.
+    if isinstance(seg, ArraySegment):
+        if not remaining and has_array_layer(field_spec.shape):
+            return {seg.name: inner}
+        # A single-level array (extra_iter == 0) gets a constraint-valid list;
+        # nested `list[list[...]]` levels (extra_iter > 0) carry no min_length>1
+        # or uniqueness constraint in any current schema, so minimal nesting
+        # suffices. Add per-level constraint handling here if one ever does --
+        # the row would otherwise be short on the unmutated `::valid` row.
+        if extra_iter == 0:
+            return {seg.name: _array_with_target(inner, field_spec, spec_name)}
+        wrapped: Any = inner
+        for _ in range(1 + extra_iter):
+            wrapped = [wrapped]
+        return {seg.name: wrapped}
+    if remaining and has_array_layer(field_spec.shape):
+        return {seg.name: _array_with_target(inner, field_spec, spec_name)}
+    return {seg.name: inner}
+
+
+def _array_with_target(
+    target_element: object, field_spec: FieldSpec, spec_name: str
+) -> list[Any]:
+    """Return a constraint-valid single-level list holding the target element.
+
+    `value_for_field` builds a list that satisfies the field's array
+    constraints (min length, unique items); the target-reaching element
+    replaces the first slot. A min_length>1 or uniqueness constraint then
+    holds on the unmutated `::valid` row -- a bare `[target_element]` would
+    leave the row short or, after `deep_merge` replaces the base row's list,
+    drop the elements that satisfied the constraint.
+    """
+    full = value_for_field(field_spec, spec_name)
+    if isinstance(full, list) and full:
+        full[0] = target_element
+        return full
+    return [target_element]
+
+
+def _element_discriminator(check: Check) -> _ElementDiscriminator | None:
+    """Return the element-level discriminator for a Check, or None.
+
+    Bundles the discriminator field, the value to seed, and the depth at
+    which to seed it (the innermost array segment in the target path).
+    The check_ir invariant is that nested-union gating composes at most
+    one `ElementGuard` per Check; more than one would mean the gate
+    composition rule changed without updating the scaffold, so raise to
+    surface the gap rather than silently dropping guards.
+    """
+    element_guards = [g for g in check.guards if isinstance(g, ElementGuard)]
+    if len(element_guards) > 1:
+        raise NotImplementedError(
+            f"Check carries {len(element_guards)} ElementGuards "
+            f"({element_guards!r}); the scaffold only seeds one. Update "
+            "the scaffold builder when the gate composition rule changes."
+        )
+    if not element_guards or not element_guards[0].values:
+        return None
+    guard = element_guards[0]
+    segments = check.target.segments
+    for i in range(len(segments) - 1, -1, -1):
+        if isinstance(segments[i], ArraySegment):
+            return _ElementDiscriminator(
+                field=guard.discriminator, value=guard.values[0], depth=i
+            )
+    return None
+
+
+def generate_scaffold(
+    check: Check, spec: ModelSpec, *, leaf_value: object = _UNSET
+) -> dict[str, Any]:
+    """Build a sparse dict from null to the target field of a Check.
+
+    `leaf_value`, when set, seeds that value at the target instead of the
+    field's synthesized value -- used to place a known-valid value (e.g. a
+    literal alternative) at the check's target for the `::valid` row.
+    """
+    segments = check.target.segments
+    if not segments:
+        return {}
+
+    if len(segments) == 1:
+        seg0 = segments[0]
+        field_spec = _find_field_spec(spec.fields, seg0.name)
+        if field_spec is None:
+            return {}
+        # A `forbid_if` the base row triggers forbids this field; disable the
+        # condition so the field can be set without invalidating the row.
+        overrides = condition_overrides_for_present_field(spec, seg0.name)
+        if leaf_value is not _UNSET:
+            return {**overrides, seg0.name: _nest_leaf_value(leaf_value, field_spec)}
+        if field_spec.is_required:
+            return {}
+        return {**overrides, seg0.name: value_for_field(field_spec, spec.name)}
+
+    return _walk_to_target(
+        segments,
+        spec.fields,
+        spec.name,
+        discriminator=_element_discriminator(check),
+        leaf_value=leaf_value,
+    )
+
+
+def generate_model_scaffold(check: ModelCheck, spec: ModelSpec) -> dict[str, Any]:
+    """Build a constraint-satisfying scaffold for a model-level check.
+
+    Two target shapes need no scaffold and return `{}`:
+
+    - a `Direct` target -- a top-level model constraint, whose fields live
+      at the row root;
+    - a map-first `Iterated` target -- a `dict[K, Model]` value-model
+      constraint. The mutation (`map_path=`) owns map navigation: it corrupts
+      the base row's single map entry in place, or stubs one when the map is
+      absent. Unlike an array, a dict scaffold can't replace a base-row map
+      entry under `deep_merge`'s recursive dict merge, so there is nothing to
+      add here.
+
+    An array-first `Iterated` target walks the path with `_walk_to_target`:
+    every model on the way -- including the constrained model at the leaf --
+    is built as a valid base row, so the constraint under test (e.g. a
+    scope's `require_any_of`) is satisfied on the unmutated `::valid` row and
+    the only violation is the one the mutation introduces.
+
+    An `Iterated` target is array-first exactly when its outermost frame is
+    an `ArraySegment` (guaranteed named, so it heads `iter_frames`); a
+    map-first target's mutation owns navigation, matching the former
+    map-path case.
+    """
+    target = check.target
+    if isinstance(target, Iterated) and isinstance(
+        target.iter_frames[0][1], ArraySegment
+    ):
+        return _walk_to_target(
+            target.segments, spec.fields, spec.name, discriminator=None
+        )
+    return {}