Skip to content

Official Codebase of 3DCodeVerse

Python
37.6 KB
Raw Blame
"""Scene placement gate ``scene_placement``: floating / sunken / unsupported / interpenetrating
assets, measured — not judged."""

from __future__ import annotations

import functools
import logging
from collections.abc import Callable, Sequence
from typing import TYPE_CHECKING, Any

from pydantic import BaseModel, ConfigDict, Field

from codeverse3d.config import Placement, get_settings
from codeverse3d.contracts.artifacts import GateFinding, GateReport, Severity
from codeverse3d.conventions import to_snake
from codeverse3d.proc import read_json_or_none
from codeverse3d.spatial.node import runtime_js_dir
from codeverse3d.workspace import Workspace

if TYPE_CHECKING:
    from codeverse3d.spatial.probes import SceneProbeResult

log = logging.getLogger(__name__)

GATE = "scene_placement"
MAX_FINDINGS_PER_KIND = 8
FREE_EXEMPT_MIN_ROWS = 2
CANTILEVER_MIN_COLUMNS, CANTILEVER_MAX_RESTING = 4, 1

INDOOR_WORDS = frozenset({
    "attic", "basement", "bathroom", "bedroom", "cabin", "cellar", "chamber", "classroom", "cockpit", "corridor", "garage", "hall", "hut", "indoor",
    "indoors", "inside", "interior", "kitchen", "lab", "laboratory", "library", "lobby", "office", "room", "studio", "tent", "warehouse", "workshop",
})
PLACEMENT_WORDS = "placement_words.json"


class _SeatedWords(BaseModel):
    model_config = ConfigDict(extra="ignore", frozen=True)

    buried_ok: frozenset[str]
    slope_ok: frozenset[str]
    partial_ok: frozenset[str]
    partial_ok_frac: float


@functools.cache
def _seated_words() -> _SeatedWords:
    return _SeatedWords.model_validate_json((runtime_js_dir() / "lib" / PLACEMENT_WORDS).read_text(encoding="utf-8"))


def _nums(v: object) -> list[float] | None:
    """Three numbers, or None."""
    if not isinstance(v, list | tuple) or len(v) != 3:
        return None
    try:
        return [float(x) for x in v]
    except (TypeError, ValueError):
        return None


class AssetRow(BaseModel):
    """One row of the census placement table (``host_placement.mjs``)."""

    model_config = ConfigDict(extra="ignore")

    name: str
    zone: str = ""
    exempt: str = ""
    bbox: dict[str, Any] | None = None
    ground_gap_m: float | None = None
    support: str = ""
    sunk_m: float = 0.0
    sunk_into: str = ""
    on_water: bool = False
    attached: list[str] = Field(default_factory=list)
    columns: int = Field(default=0, description="foot columns probed (≤ 5: the lowest vertex and the ±x / ±z extremes of the foot band)")
    gap_max_m: float | None = Field(default=None, description="the LARGEST column gap (ground_gap_m is the smallest); a row "
                                                              "measured before 2026-10-14 carries none")
    columns_resting: int | None = Field(default=None, description="columns within contact of their support, or buried; "
                                                                 "None before 2026-10-14")
    tilt_m: float | None = Field(default=None, description="gap_max_m - ground_gap_m: how unevenly the feet meet the ground")
    inner: list[str] = Field(
        default_factory=list,
        description="named descendants of this row (host_placement.MAX_INNER_NAMES) — a zone "
                    "often wraps its content in one group, and the plan-contents check has to "
                    "see through it",
    )
    families: dict[str, dict[str, float]] = Field(
        default_factory=dict,
        description="per named family below this row with >= 2 members: {n, size_m} — the median "
                    "largest extent of ONE member, so a wrapper holding twelve fence panels is "
                    "scale-checked as a fence panel, not as the 15 m run",
    )

    def instance_size(self, key: str) -> tuple[int, float]:
        """``(members, median largest extent)`` of the family the plan's ``key`` names inside
        this row, ``(0, 0.0)`` when the row is not a wrapper of such instances."""
        best = (0, 0.0)
        for fam, v in self.families.items():
            if key in to_snake(fam) and int(v.get("n", 0)) >= 2 and float(v.get("size_m", 0.0)) > 0 and int(v["n"]) > best[0]:
                best = (int(v["n"]), float(v["size_m"]))
        return best

    @property
    def qualified(self) -> str:
        """``Zone/Name`` — routes to the zone's file in refine tasks, stays unique per asset."""
        return f"{self.zone}/{self.name}" if self.zone else self.name

    @property
    def height(self) -> float:
        size = _nums((self.bbox or {}).get("size"))
        return size[1] if size else 0.0

    def bbox_data(self) -> dict[str, list[float]] | None:
        """``{"center", "size"}`` of the row's box in the GLB frame, on every per-asset finding."""
        b = self.bbox or {}
        lo, hi = _nums(b.get("min")), _nums(b.get("max"))
        if lo is None or hi is None:
            return None
        return {"center": [round((lo[i] + hi[i]) / 2, 3) for i in range(3)], "size": [round(hi[i] - lo[i], 3) for i in range(3)]}


class Interpenetration(BaseModel):
    model_config = ConfigDict(extra="ignore")

    a: str
    b: str
    zone_a: str = ""
    zone_b: str = ""
    aabb_overlap: float = 0.0
    inside_frac: float = 0.0


class SceneryRoots(BaseModel):
    """The roots outside every marked zone."""

    model_config = ConfigDict(extra="ignore")

    n: int = 0
    names: list[str] = Field(default_factory=list)


class PlacementTable(BaseModel):
    model_config = ConfigDict(extra="ignore")

    assets: list[AssetRow] = Field(default_factory=list)
    interpenetrations: list[Interpenetration] = Field(default_factory=list)
    total: int = 0
    checked: int = 0
    truncated: bool = False
    exempt: dict[str, int] = Field(default_factory=dict)
    scenery: SceneryRoots = Field(default_factory=SceneryRoots,
                                  description="roots outside the marked zones (none in a table measured before D111)")
    ground_y: float | None = None
    notes: list[str] = Field(default_factory=list)
    thresholds: dict[str, float] = Field(default_factory=dict, description="the probe's own measurement constants")
    error: str = ""


def _words(name: str) -> set[str]:
    return {w for w in to_snake(name).split("_") if w and not w.isdigit()}


def infer_indoor(text: str) -> bool:
    """True when the plan's setting / environment text names an indoor word (fallback for plans without ``ScenePlan.interior``)."""
    return bool(_words(text) & INDOOR_WORDS)


def is_interior(plan: Any) -> bool:
    """The plan's typed ``interior`` flag whenever it has one, True OR False."""
    flag = plan.get("interior") if isinstance(plan, dict) else getattr(plan, "interior", None)
    if isinstance(flag, bool):
        return flag
    return infer_indoor(setting_text(plan))


LANGUAGE_WORDS: dict[str, dict[str, str]] = {
    "scene_threejs": {
        "seat": "seat it with heightAt(x, z) or on the surface it stands on",
        "free": "{name}.userData.placement = 'free'",
        "no_fog_msg": "scene.fog is not set — frames read as thin_atmosphere (32/48 measured runs)",
        "no_fog": "in buildEnv set scene.fog = new THREE.Fog(<sky horizon hex>, near, far) with the plan's numbers",
        "no_background_msg": "scene.background is not set (renders on the raw clear colour)",
        "no_background": "in buildEnv set scene.background to the sky colour or sky texture the plan names",
        "fog_far": ("fog far must reach >= {need:.0f} m ({spans:g} x the plan span; measured from scene.fog) so whatever "
                    "lies past the bounds fades with distance instead of cutting off — the terrain, buildings, trees or "
                    "water out there then read as aerial perspective"),
        "place": "import its builder / clone its GLB",
        "in_zone": "as a direct child of the group the zone's build returns (what is added straight to the scene is not the zone's)",
        "free_exempt": ("userData.placement = 'free' is for hanging / airborne things only (a bird, a hung lantern, a drone): "
                        "delete the tag on everything that stands on something and seat it with heightAt(x, z) or on its support"),
        "cantilever": "seat every foot: follow the ground with heightAt(x, z) at each corner, sink it a few cm, or shorten the overhang",
    },
    "scene_blender": {
        "seat": "seat it with ctx.height_at(x, y) or on the surface it stands on",
        "free": '{name}["placement"] = "free"',
        "no_fog_msg": "the scene has no atmosphere: no world Volume, bounded fog volume or mist — frames read as thin_atmosphere",
        "no_fog": ("in build_env link a Volume Scatter / Principled Volume to the World Output's Volume (density "
                   "0.003-0.008, tinted like the sky horizon) or place a bounded fog volume over the play area"),
        "no_background_msg": "the world has no sky: no Sky Texture or Background colour on the world output",
        "no_background": "in build_env give scene.world a Sky Texture (or the plan's sky colour on its Background node)",
        "fog_far": ("thin the fog so 1/density >= {need:.0f} m ({spans:g} x the plan span; measured from the world volume) "
                    "so whatever lies past the bounds fades with distance instead of cutting off — the terrain, buildings, "
                    "trees or water out there then read as aerial perspective"),
        "place": "place a collection-instance Empty of ctx.assets['<snake>']",
        "in_zone": "as a root object linked into the zone's collection",
        "free_exempt": ('obj["placement"] = "free" is for hanging / airborne things only (a bird, a hung lantern, a drone): '
                        "delete the tag on everything that stands on something and seat it with ctx.height_at(x, y) at its "
                        "lowest evaluated vertices"),
        "cantilever": ("seat every foot: follow the ground with ctx.height_at(x, y) at each corner (its lowest evaluated "
                       "vertex on the lowest ground under it), sink it a few cm, or shorten the overhang"),
    },
}


def placement_words(language: str | None) -> dict[str, str]:
    return LANGUAGE_WORDS.get(str(language or "scene_threejs"), LANGUAGE_WORDS["scene_threejs"])


def _f(sev: Severity, msg: str, *, target: str, hint: str = "", kind: str, **data: Any) -> GateFinding:
    return GateFinding(gate=GATE, severity=sev, target=target, message=msg, fix_hint=hint, data={"kind": kind, **data})


def _support_label(row: AssetRow, ground_y: float | None) -> str:
    if row.support and row.support != "ground_y":
        return row.support
    return f"the ground (census ground_y = {ground_y:.2f} m)" if ground_y is not None else "the ground"


def _sunk_severity(row: AssetRow, p: Placement) -> Severity | None:
    """WARN / ERROR / None for a buried foot, honouring height fraction and name words."""
    if row.sunk_m <= 0 or row.on_water:
        return None
    words, seated = _words(row.name), _seated_words()
    if words & (seated.buried_ok | seated.slope_ok):
        return None
    frac = row.sunk_m / row.height if row.height > 1e-6 else 1.0
    if words & seated.partial_ok:
        if frac <= seated.partial_ok_frac:
            return None
        return Severity.ERROR if row.sunk_m > p.sunk_error_m else Severity.WARN
    if row.sunk_m > p.sunk_error_m and frac > p.sunk_error_frac:
        return Severity.ERROR
    return Severity.WARN if row.sunk_m > p.sunk_m else None


def _cantilever(row: AssetRow, p: Placement) -> bool:
    """Seated on at most ``CANTILEVER_MAX_RESTING`` of ≥ ``CANTILEVER_MIN_COLUMNS`` foot columns
    while another hangs past the outdoor floating tolerance."""
    if row.columns < CANTILEVER_MIN_COLUMNS or row.columns_resting is None or row.gap_max_m is None:
        return False
    if row.columns_resting > CANTILEVER_MAX_RESTING or row.gap_max_m <= p.floating_outdoor_m:
        return False
    return not (_words(row.name) & _seated_words().slope_ok)


def _asset_findings(rows: list[AssetRow], *, p: Placement, floating_m: float, ground_y: float | None,
                    words: dict[str, str], indoor: bool = False) -> list[GateFinding]:
    """A floating / unsupported row states its gap to the millimetre and the tolerance it was measured against."""
    out: list[GateFinding] = []
    tolerance = f"{'indoor' if indoor else 'outdoor'} tolerance {floating_m:.2f} m"
    floating: list[tuple[AssetRow, float]] = []
    for row in rows:
        q = row.qualified
        at = {"zone": row.zone, "bbox": row.bbox_data()}
        sev = _sunk_severity(row, p)
        if sev is not None:
            out.append(_f(sev, f"{q} is sunken {row.sunk_m:.2f} m into {row.sunk_into or 'the ground'}", target=q,
                          hint=f"raise {q} by {row.sunk_m:.2f} m so its lowest point sits on {row.sunk_into or 'the ground'}",
                          kind="sunken", sunk_m=row.sunk_m, into=row.sunk_into, **at))
            continue
        gap = row.ground_gap_m
        if gap is None or row.on_water:
            continue
        if row.attached:
            continue
        support = _support_label(row, ground_y)
        if row.sunk_m > 0 or gap <= p.contact_m:
            if _cantilever(row, p):
                out.append(_f(Severity.WARN, f"{q} rests on {row.columns_resting} of its {row.columns} foot columns: the others "
                                             f"hang up to {row.gap_max_m:.2f} m above {support} (tilt {row.tilt_m or 0:.2f} m)",
                              target=q, hint=f"{words['cantilever']}; a deliberately airborne thing gets "
                                             f"{words['free'].format(name=row.name)}",
                              kind="cantilevered", gap_max_m=row.gap_max_m, tilt_m=row.tilt_m, columns=row.columns,
                              columns_resting=row.columns_resting, **at))
            continue
        if gap > floating_m:
            floating.append((row, gap))
        else:
            out.append(_f(Severity.WARN, f"{q} is unsupported: hovers {gap:.3f} m above {support} and touches nothing "
                                         f"(within the {tolerance})", target=q,
                          hint=f"lower {q} by {gap:.3f} m onto {support}, or attach it to a neighbour; "
                               f"if it is meant to hang free set {words['free'].format(name=row.name)}",
                          kind="unsupported", gap_m=gap, **at))
    many = len(floating) > p.floating_error_count
    for row, gap in floating:
        q = row.qualified
        support = _support_label(row, ground_y)
        sev = Severity.ERROR if (many or gap > p.floating_error_m) else Severity.WARN
        why = (f"; ERROR past {p.floating_error_m:.2f} m" if gap > p.floating_error_m
               else f"; ERROR because {len(floating)} rows float, more than {p.floating_error_count}" if many else "")
        out.append(_f(sev, f"{q} is floating {gap:.3f} m above {support} (touches nothing; {tolerance}{why})", target=q,
                      hint=f"lower {q} by {gap:.3f} m onto {support} — {words['seat']}; "
                           f"a deliberately airborne thing gets {words['free'].format(name=row.name)}",
                      kind="floating", gap_m=gap, zone=row.zone, bbox=row.bbox_data()))
    return out


def _pair_findings(pairs: list[Interpenetration], p: Placement, rows: dict[str, AssetRow]) -> list[GateFinding]:
    out: list[GateFinding] = []
    best: dict[tuple[str, str], Interpenetration] = {}
    for pr in pairs:
        if pr.aabb_overlap <= p.overlap_warn:
            continue
        key = tuple(sorted((f"{pr.zone_a}/{pr.a}", f"{pr.zone_b}/{pr.b}")))
        if key not in best or pr.aabb_overlap > best[key].aabb_overlap:
            best[key] = pr
    for pr in best.values():
        qa = f"{pr.zone_a}/{pr.a}" if pr.zone_a else pr.a
        qb = f"{pr.zone_b}/{pr.b}" if pr.zone_b else pr.b
        sev = Severity.ERROR if pr.aabb_overlap > p.overlap_error else Severity.WARN
        row = rows.get(qa)
        out.append(_f(sev, f"interpenetration: {qa} and {qb} overlap ({pr.aabb_overlap:.0%} of the smaller box; "
                           f"{pr.inside_frac:.0%} of its vertices inside the other)", target=qa,
                      hint=f"move {qa} out of {qb} or shrink one of them so their boxes share ≤ {p.overlap_warn:.0%}",
                      kind="interpenetration", overlap=pr.aabb_overlap, inside_frac=pr.inside_frac, other=qb, zone=pr.zone_a,
                      bbox=row.bbox_data() if row is not None else None))
    return out


def _free_exempt_finding(t: PlacementTable, p: Placement, words: dict[str, str]) -> GateFinding | None:
    """One finding per report."""
    free = [r for r in t.assets if r.exempt == "free"]
    n = t.checked + len(free)
    if len(free) < FREE_EXEMPT_MIN_ROWS or n == 0:
        return None
    share = len(free) / n
    if share <= p.free_exempt_warn:
        return None
    sev = Severity.ERROR if share > p.free_exempt_error else Severity.WARN
    names = [r.qualified for r in free[:8]]
    listed = ", ".join(names) + (f" (+{len(free) - 8} more)" if len(free) > 8 else "")
    return _f(sev, f"{len(free)} of {n} placed assets are tagged placement='free' ({share:.0%}) and skip every placement "
                   f"check: {listed}", target="scene", hint=words["free_exempt"],
              kind="free_exempt", free=len(free), of=n, share=round(share, 3), names=names)


def _cap_per_kind(findings: list[GateFinding]) -> list[GateFinding]:
    """Keep the worst ``MAX_FINDINGS_PER_KIND`` per kind (ERROR first, then magnitude)."""
    rank = {Severity.ERROR: 0, Severity.WARN: 1, Severity.INFO: 2}
    by_kind: dict[str, list[GateFinding]] = {}
    for f in findings:
        by_kind.setdefault(str(f.data.get("kind")), []).append(f)
    out: list[GateFinding] = []
    for kind, fs in by_kind.items():
        fs.sort(key=lambda f: (rank[f.severity], -float(f.data.get("gap_m") or f.data.get("sunk_m") or f.data.get("overlap")
                                                        or f.data.get("gap_max_m") or 0)))
        out.extend(fs[:MAX_FINDINGS_PER_KIND])
        if len(fs) > MAX_FINDINGS_PER_KIND:
            out.append(_f(Severity.INFO, f"… and {len(fs) - MAX_FINDINGS_PER_KIND} more {kind} finding(s) not listed", target="scene",
                          kind="truncated", of=kind))
    return out


ASSET_KINDS = ("floating", "sunken", "unsupported", "interpenetration", "cantilevered")


def placement_findings(table: dict[str, Any] | PlacementTable, *, indoor: bool = False, language: str | None = None,
                       thresholds: Placement | None = None) -> GateReport:
    """The ``scene_placement`` GateReport for one census placement table."""
    t = table if isinstance(table, PlacementTable) else PlacementTable.model_validate(table or {})
    if t.error:
        return GateReport.of(GATE, [
            _f(Severity.WARN, f"placement probe failed: {t.error[:300]}", target="scene", kind="probe_failed",
               hint="harness instrumentation, not your code; the placement check was skipped this round")])
    p = thresholds or get_settings().placement
    floating_m = p.floating_indoor_m if indoor else p.floating_outdoor_m
    words = placement_words(language)
    rows = [r for r in t.assets if not r.exempt]
    raw = (_asset_findings(rows, p=p, floating_m=floating_m, ground_y=t.ground_y, words=words, indoor=indoor)
           + _pair_findings(t.interpenetrations, p, {r.qualified: r for r in t.assets}))
    free = _free_exempt_finding(t, p, words)
    findings = _cap_per_kind(raw) + ([free] if free is not None else [])
    counts = {k: sum(1 for f in raw if f.data.get("kind") == k) for k in ASSET_KINDS}
    listed = {k: sum(1 for f in findings if f.data.get("kind") == k) for k in ASSET_KINDS}
    n_free = sum(1 for r in t.assets if r.exempt == "free")
    free_share = n_free / (t.checked + n_free) if t.checked + n_free else 0.0
    n_exempt = sum(t.exempt.values())

    def shown(kind: str) -> str:
        return f"{counts[kind]}" + (f" ({listed[kind]} listed)" if listed[kind] < counts[kind] else "")

    summary = (f"{t.checked} assets checked ({t.total} placed, {n_exempt} exempt): {shown('floating')} floating, "
               f"{shown('sunken')} sunken, {shown('unsupported')} unsupported, {shown('interpenetration')} interpenetrating"
               + (f", {shown('cantilevered')} cantilevered" if counts["cantilevered"] else "")
               + (f", {n_free} tagged free ({free_share:.0%})" if n_free else "")
               + (f"; {t.scenery.n} scenery roots outside the zones not measured" if t.scenery.n else "")
               + f"; {'indoor' if indoor else 'outdoor'} tolerance {floating_m * 100:.0f} cm, ERROR past "
                 f"{p.floating_error_m * 100:.0f} cm or more than {p.floating_error_count} floating"
               + ("; table truncated (first 400 assets / time budget)" if t.truncated else ""))
    findings.insert(0, _f(Severity.INFO, summary, target="scene", kind="summary", counts=counts, listed=listed, checked=t.checked,
                          total=t.total, exempt=t.exempt, free=n_free, free_share=round(free_share, 3), truncated=t.truncated,
                          scenery=t.scenery.n,
                          thresholds={**p.model_dump(), "floating_m": floating_m, "indoor": indoor},
                          probe_thresholds=dict(t.thresholds)))
    return GateReport.of(GATE, findings)


# --------------------------------------------------------------------------- plan-aware checks
SCALE_WARN, SCALE_ERROR = 2.5, 4.0
FOG_FAR_MIN_SPANS, FOG_DENSITY_MAX_PER_SPAN = 2.0, 1.5
BOUNDS_MARGIN_MIN_M = 5.0
BOUNDS_MARGIN_FRAC = 0.10
WORLD_EDGE_REACH_FACTOR = 1.25
WORLD_EDGE_MIN_HEIGHT_M = 2.0
RING_MIN_COPIES = 8
RING_BACKDROP_FRAC = 0.6
RING_RADIUS_CV_MAX = 0.08
RING_GAP_CV_MAX = 0.25
RING_SIZE_CV_MAX = 0.25
RING_HINT = ("break the pattern — uneven spacing, mixed sizes and silhouettes, clusters and gaps — or close the distance "
             "some other way the place suggests (a ridge line, a treeline, buildings, open water); the check calls a ring "
             "when >= {min_n} copies have radius spread <= {rcv:.0%}, spacing spread <= {gcv:.0%} and size spread <= {scv:.0%}")
WORLD_EDGE_HINT = ("continue the place past the bounds in whatever form the brief implies — more of the same terrain, the "
                   "rest of the street, a treeline, water to the horizon, a wall — with something >= {min_h:.0f} m tall "
                   "reaching past ~{need:.0f} m from the bounds centre, and the fog closing the distance (fog_short measures "
                   "its reach); vary any repeated element out there (stamped_ring measures radius / spacing / size spread)")


def _plan_zones(plan: Any) -> list[tuple[str, list[str]]]:
    zones = (plan.get("zones") if isinstance(plan, dict) else getattr(plan, "zones", None)) or []
    out = []
    for z in zones:
        name = z.get("name") if isinstance(z, dict) else getattr(z, "name", "")
        contents = (z.get("contents") if isinstance(z, dict) else getattr(z, "contents", None)) or []
        if name:
            out.append((str(name), [str(c) for c in contents]))
    return out


def _plan_asset_sizes(plan: Any) -> dict[str, float]:
    assets = (plan.get("assets") if isinstance(plan, dict) else getattr(plan, "assets", None)) or []
    out: dict[str, float] = {}
    for a in assets:
        name = a.get("name") if isinstance(a, dict) else getattr(a, "name", "")
        size = (a.get("approx_size_m") if isinstance(a, dict) else getattr(a, "approx_size_m", None)) or ()
        try:
            m = max(float(v) for v in size)
        except (TypeError, ValueError):
            continue
        if name and m > 0.05:
            out[to_snake(name)] = m
    return out


def _plan_bounds(plan: Any) -> tuple[tuple[float, ...], tuple[float, ...]] | None:
    b = plan.get("bounds") if isinstance(plan, dict) else getattr(plan, "bounds", None)
    if b is None:
        return None
    try:
        if isinstance(b, dict):
            c, e = b.get("center"), b.get("extents")
            lo = tuple(float(c[i]) - float(e[i]) / 2 for i in range(3))
            hi = tuple(float(c[i]) + float(e[i]) / 2 for i in range(3))
            return lo, hi
        return tuple(map(float, b.min)), tuple(map(float, b.max))
    except (TypeError, ValueError, IndexError, AttributeError):
        return None


def _row_names(row: AssetRow) -> str:
    """The row's own name plus its named descendants, snake-cased for loose matching."""
    return " ".join(to_snake(n) for n in [row.name, *row.inner])


def contract_findings(census: dict[str, Any] | None, plan: Any,
                      unavailable: Sequence[str] = ()) -> list[GateFinding]:
    """Deterministic plan-vs-census checks."""
    if not isinstance(census, dict) or plan is None:
        return []
    words = placement_words(census.get("language"))
    out: list[GateFinding] = []
    groups = {to_snake(g.get("name", "")): g for g in (census.get("groups") or [])
              if isinstance(g, dict)}
    if "fog" in census and census.get("fog") is None:
        out.append(_f(Severity.ERROR, words["no_fog_msg"], target="env", kind="no_fog", hint=words["no_fog"]))
    if "background" in census and census.get("background") is None:
        out.append(_f(Severity.ERROR, words["no_background_msg"], target="env", kind="no_background",
                      hint=words["no_background"]))
    fog = census.get("fog")
    pb = _plan_bounds(plan)
    if isinstance(fog, dict) and pb and not is_interior(plan):
        span = max(pb[1][0] - pb[0][0], pb[1][2] - pb[0][2])
        far, density = fog.get("far"), fog.get("density")
        short = ""
        if isinstance(far, int | float) and span > 0 and far < FOG_FAR_MIN_SPANS * span:
            short = f"fog far {far:g} m ends inside the plan's {span:g} m world ({far / span:.1f}x)"
        elif isinstance(density, int | float) and span > 0 and density > FOG_DENSITY_MAX_PER_SPAN / span:
            short = f"fog density {density:g} dissolves the plan's {span:g} m world within {1 / density:.0f} m"
        if short:
            out.append(_f(Severity.WARN, short + " — past it the land is the background colour while the unfogged sky "
                          "stays sharp: a world edge and backdrops floating in the sky",
                          target="env", kind="fog_short", fog=fog, plan_span_m=round(span, 1),
                          hint=words["fog_far"].format(need=FOG_FAR_MIN_SPANS * span, spans=FOG_FAR_MIN_SPANS)))
    bounds = _plan_bounds(plan)
    if bounds and isinstance(census.get("groups"), list):
        lo, hi = bounds
        half = max(hi[0] - lo[0], hi[2] - lo[2]) / 2
        for g in census["groups"]:
            for st in (g.get("stamps") if isinstance(g, dict) else None) or []:
                if not isinstance(st, dict):
                    continue
                n, r = int(st.get("n") or 0), float(st.get("radius_m") or 0)
                rcv, gcv, scv = (float(st.get(k) or 0) for k in ("radius_cv", "gap_cv", "size_cv"))
                if (n >= RING_MIN_COPIES and half > 0 and r >= RING_BACKDROP_FRAC * half
                        and rcv <= RING_RADIUS_CV_MAX and gcv <= RING_GAP_CV_MAX and scv <= RING_SIZE_CV_MAX):
                    where = f"{g.get('name', '?')}/{st.get('name', '?')}"
                    out.append(_f(Severity.WARN,
                                  f"{where}: {n} near-identical copies stamped evenly on a {r:.0f} m ring round the world "
                                  f"(radius spread {rcv:.0%}, spacing spread {gcv:.0%}, size spread {scv:.0%}) — a toy backdrop",
                                  target=str(g.get("name", "overall")), kind="stamped_ring", n=n, radius_m=r,
                                  radius_cv=rcv, gap_cv=gcv, size_cv=scv,
                                  hint=RING_HINT.format(min_n=RING_MIN_COPIES, rcv=RING_RADIUS_CV_MAX, gcv=RING_GAP_CV_MAX,
                                                        scv=RING_SIZE_CV_MAX)))
    groups = census.get("groups")
    if bounds and isinstance(groups, list) and not is_interior(plan):
        lo, hi = bounds
        cx, cz = (lo[0] + hi[0]) / 2, (lo[2] + hi[2]) / 2
        half = max(hi[0] - lo[0], hi[2] - lo[2]) / 2
        need = WORLD_EDGE_REACH_FACTOR * half
        reach = 0.0
        for g in groups:
            b = g.get("bbox") if isinstance(g, dict) else None
            bmin, bmax = (_nums(b.get("min")), _nums(b.get("max"))) if isinstance(b, dict) else (None, None)
            if bmin is None or bmax is None or g.get("kind") not in ("content", "ground"):
                continue
            if (bmax[1] - bmin[1]) < WORLD_EDGE_MIN_HEIGHT_M:
                continue
            r = max(abs(bmin[0] - cx), abs(bmax[0] - cx), abs(bmin[2] - cz), abs(bmax[2] - cz))
            reach = max(reach, r)
        if 0 < reach < need:
            out.append(_f(Severity.WARN,
                          f"the world ends at its bounds: the farthest standing geometry (>= {WORLD_EDGE_MIN_HEIGHT_M:.0f} m "
                          f"tall) reaches {reach:.0f} m from the bounds centre and nothing stands past ~{need:.0f} m — "
                          "the edge of the built world is in view from every camera that looks outward",
                          target="env", kind="world_edge", reach_m=round(reach, 1), need_m=round(need, 1),
                          hint=WORLD_EDGE_HINT.format(min_h=WORLD_EDGE_MIN_HEIGHT_M, need=need)))
    table = census.get("placement") if isinstance(census.get("placement"), dict) else None
    rows = [AssetRow.model_validate(r) for r in (table.get("assets") or [])] if table else []
    if not rows:
        return out
    by_zone: dict[str, list[AssetRow]] = {}
    for r in rows:
        by_zone.setdefault(to_snake(r.zone), []).append(r)
    all_names = " ".join(_row_names(r) for r in rows)
    gone = {to_snake(u) for u in unavailable}
    cut = bool(table.get("truncated")) and int(table.get("total") or 0) > len(rows)
    at_cut = to_snake(rows[-1].zone) if cut else None
    built = {to_snake(str(g.get("name", ""))) for g in census.get("groups") or []
             if isinstance(g, dict) and g.get("kind") in ("content", "ground")}   # an EMPTY group placed nothing
    for zone_name, contents in _plan_zones(plan):
        zk = to_snake(zone_name)
        placed = by_zone.get(zk, [])
        expected = [c for c in contents if to_snake(c) not in gone]
        if not placed and expected and cut and zk in built:
            out.append(_f(Severity.INFO, f"zone {zone_name} was not measured: the placement table was truncated before "
                                         "its rows (its group is in the census)", target=zone_name, kind="zone_unmeasured"))
            continue
        if not placed and expected:
            out.append(_f(Severity.ERROR, f"zone {zone_name} placed nothing (plan lists: {', '.join(expected[:6])})",
                          target=zone_name, kind="zone_empty",
                          hint=f"build the zone group named '{zone_name}' and place its planned contents"))
            continue
        zone_names = " ".join(_row_names(r) for r in placed)
        missing = [c for c in expected if to_snake(c) not in zone_names and to_snake(c) not in all_names]
        if missing and zk == at_cut:
            out.append(_f(Severity.INFO, f"zone {zone_name} was only partly measured: the placement table was truncated "
                                         f"inside it, so {', '.join(missing[:5])} may lie past the cut",
                          target=zone_name, kind="zone_unmeasured", missing=missing[:8]))
        elif missing:
            out.append(_f(Severity.ERROR,
                          f"zone {zone_name} is missing planned contents: {', '.join(missing[:5])}"
                          + (f" (+{len(missing) - 5} more)" if len(missing) > 5 else ""),
                          target=zone_name, kind="missing_content", missing=missing[:8],
                          hint=f"place each listed asset ({words['place']}) inside this "
                               f"zone's bbox, {words['in_zone']}, AND give the object the plan's name for it — every gate and the "
                               "judge find it by that name, so a lantern called 'LanternPost1' reads as absent"))
    sizes = _plan_asset_sizes(plan)
    for r in rows:
        size = _nums((r.bbox or {}).get("size"))
        if r.exempt or size is None:
            continue
        rk = to_snake(r.name)
        key = next((k for k in sizes if k in rk), "")
        if not key:
            continue
        n, measured = r.instance_size(key)
        what = f"each of the {n} {key} instances in {r.qualified}" if n else r.qualified
        if not n:
            measured = max(size)
        f = measured / sizes[key]
        if f > SCALE_ERROR or f < 1 / SCALE_ERROR:
            sev = Severity.ERROR
        elif f > SCALE_WARN or f < 1 / SCALE_WARN:
            sev = Severity.WARN
        else:
            continue
        out.append(_f(sev, f"{what} measures {measured:.2f} m but the plan sized {key} at ~{sizes[key]:.2f} m ({f:.1f}x)",
                      target=r.qualified, kind="scale", factor=round(f, 2), zone=r.zone, instances=n, bbox=r.bbox_data(),
                      hint=f"scale {'each ' + key if n else r.name} so its largest dimension is ~{sizes[key]:.2f} m as planned"))
    bounds = _plan_bounds(plan)
    if bounds:
        lo, hi = bounds
        margin = max(BOUNDS_MARGIN_MIN_M, BOUNDS_MARGIN_FRAC * max(hi[0] - lo[0], hi[2] - lo[2]))
        planned = {to_snake(c) for _, contents in _plan_zones(plan) for c in contents}
        for r in rows:
            bmin, bmax = _nums((r.bbox or {}).get("min")), _nums((r.bbox or {}).get("max"))
            if r.exempt or bmin is None or bmax is None:
                continue
            names = _row_names(r)
            key = next((c for c in sorted(planned) if c in names), "")
            if not key:
                continue
            fully_out = (bmin[0] > hi[0] + margin or bmax[0] < lo[0] - margin
                         or bmin[2] > hi[2] + margin or bmax[2] < lo[2] - margin)
            if fully_out:
                out.append(_f(Severity.WARN, f"{r.qualified} (planned content '{key}') sits entirely outside the plan "
                                             f"bounds + {margin:.0f} m (x {bmin[0]:.0f}..{bmax[0]:.0f}, z {bmin[2]:.0f}..{bmax[2]:.0f})",
                              target=r.qualified, kind="out_of_bounds", zone=r.zone, bbox=r.bbox_data(), planned=key,
                              margin_m=round(margin, 1),
                              hint="a planned asset is measured where the plan puts it (inside its zone bbox / the plan "
                                   "bounds); scenery that continues the place past the bounds is free and is not this"))
    return out


def placement_census(ws: Workspace, probe: Callable[..., SceneProbeResult], *, force_probe: bool = False,
                     timeout_s: float = 60.0) -> dict[str, Any]:
    """The census dict carrying ``placement``."""
    census = None if force_probe else read_json_or_none(ws.artifacts / "census.json")
    if isinstance(census, dict) and isinstance(census.get("placement"), dict):
        return census
    res = probe(ws, timeout_s=timeout_s)
    if res.errors:
        return {"placement": {"error": res.errors[0]}}
    census = res.census or {}
    if not isinstance(census.get("placement"), dict):
        census["placement"] = {"error": "the scene did not boot, so nothing was placed" if not census else "probe driver returned no placement table"}
    return census


def setting_text(plan: Any) -> str:
    """The plan text the indoor/outdoor rule reads (``setting`` / ``environment`` / ``title``),
    from a plan dict or a ScenePlan."""
    if isinstance(plan, dict):
        return " ".join(str(plan.get(k) or "") for k in ("setting", "environment", "title"))
    return " ".join(str(getattr(plan, k, "") or "") for k in ("setting", "environment", "title"))


def placement_gate_safe(census: dict[str, Any] | None, *, plan: Any = None,
                        unavailable: Sequence[str] = ()) -> GateReport | None:
    """Round-gate entry."""
    try:
        table = (census or {}).get("placement")
        if not isinstance(table, dict):
            return None
        report = placement_findings(table, indoor=is_interior(plan), language=(census or {}).get("language"))
        extra = _cap_per_kind(contract_findings(census, plan, unavailable=unavailable))
        if extra:
            report = GateReport.of(GATE, report.findings + extra, duration_ms=report.duration_ms)
        return report
    except Exception as e:  # noqa: BLE001 — advisory instrumentation must not fail the round
        log.warning("scene placement gate failed: %s", e)
        return GateReport.of(GATE, [
            _f(Severity.WARN, f"placement probe failed: {type(e).__name__}: {e}"[:400], target="scene", kind="probe_failed")])


def placement_table_text(table: dict[str, Any] | PlacementTable, *, max_rows: int = 40) -> str:
    """The per-asset table behind the findings (tool observations / prompts)."""
    t = table if isinstance(table, PlacementTable) else PlacementTable.model_validate(table or {})
    if t.error:
        return f"placement table unavailable: {t.error}"
    lines = [f"placement: {t.checked} checked of {t.total} placed; exempt {t.exempt or '{}'}; ground_y {t.ground_y}"
             + (f"; scenery (not measured): {', '.join(t.scenery.names[:8])}" if t.scenery.n else "")
             + ("; TRUNCATED" if t.truncated else "")]
    lines.append("asset | gap to support (m) | support | sunk (m) | into | water | attached")
    for r in [r for r in t.assets if not r.exempt][:max_rows]:
        lines.append(f"{r.qualified} | {'-' if r.ground_gap_m is None else f'{r.ground_gap_m:+.3f}'} | {r.support or '-'} | "
                     f"{r.sunk_m:.3f} | {r.sunk_into or '-'} | {'yes' if r.on_water else '-'} | {', '.join(r.attached[:3]) or '-'}")
    for p in t.interpenetrations[:10]:
        lines.append(f"interpenetration {p.zone_a}/{p.a} × {p.zone_b}/{p.b}: {p.aabb_overlap:.0%} box, {p.inside_frac:.0%} inside")
    lines += [f"note: {n}" for n in t.notes[:3]]
    return "\n".join(lines)