zu-checks 0.2.0__tar.gz

zu_checks-0.2.0/.gitignore

@@ -0,0 +1,66 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+
+# uv / venv
+.venv/
+uv.lock.bak
+
+# Test / type caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Zu runtime artifacts
+*.db
+zu.db
+zu.yaml.local
+zu_review.jsonl
+*.review.jsonl
+# Per-agent cost telemetry ledger — machine-local run history, not source.
+cost.jsonl
+# A recorded replay path is learned per-run and machine-local — regenerated on
+# every successful run, not source. The agent ships; its track does not.
+track.json
+# …except the flagship example ships its track on purpose, as a demo of the
+# record/replay convergence (committed; re-runs show as ordinary modifications).
+!examples/agents/vet-appointment/track.json
+
+# Editor / OS
+.idea/
+.vscode/
+.DS_Store
+
+# Claude Code local session state
+.claude/
+
+# Secrets
+.env
+.env.*
+!.env.example
+
+# Microsoft Office temp/lock files
+~$*
+
+# Internal design / strategy docs — kept local, never in the public repo
+*.docx
+*.pdf
+# BUILD.md is the internal build-sequence / deferred-gaps ledger — kept local.
+# (ARCHITECTURE.md is public: an onboarding agent needs the structural map.)
+docs/BUILD.md
+
+# Local secret — API key for live validation, never commit
+zu_demo_key.md
+*_key.md
+
+# Local PyPI publish token — never commit
+/pypi
+
+# Local Discord credentials (bot token / app secrets) — never commit
+/discord

zu_checks-0.2.0/PKG-INFO

@@ -0,0 +1,37 @@
+Metadata-Version: 2.4
+Name: zu-checks
+Version: 0.2.0
+Summary: Zu built-in checks: detectors (empty, error, js-shell, embedded-widget, bot-wall) + validators (schema, grounding)
+Project-URL: Homepage, https://github.com/k3-mt/zu
+Project-URL: Repository, https://github.com/k3-mt/zu
+License-Expression: Apache-2.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: jsonschema>=4
+Requires-Dist: zu-core==0.2.0
+Description-Content-Type: text/markdown
+
+# zu-checks
+
+The built-in **checks** that ship with the Zu base runtime — two stdlib plugin
+kinds in one package:
+
+- **detectors** (`zu_checks.detectors`) — `empty`, `error`, `js-shell`,
+  `bot-wall`. Inspect an observation and return a `Verdict`; the severity drives
+  the loop (`ESCALATE` climbs the tier ladder, `TERMINAL` ends the run).
+- **validators** (`zu_checks.validators`) — `schema` (does the result fit the
+  requested shape?) and `grounding` (does every extracted value actually appear
+  in retrieved content? — the anti-hallucination check).
+
+They're packaged together because both are pure-stdlib (schema adds only
+`jsonschema`) and always present in the base — unlike the adapter packages
+(`zu-providers`, `zu-tools`, `zu-backends`), whose separation carries distinct
+heavy optional dependencies. All register via the standard `zu.detectors` /
+`zu.validators` entry-point groups, exactly as a third-party check would.

zu_checks-0.2.0/README.md

@@ -0,0 +1,17 @@
+# zu-checks
+
+The built-in **checks** that ship with the Zu base runtime — two stdlib plugin
+kinds in one package:
+
+- **detectors** (`zu_checks.detectors`) — `empty`, `error`, `js-shell`,
+  `bot-wall`. Inspect an observation and return a `Verdict`; the severity drives
+  the loop (`ESCALATE` climbs the tier ladder, `TERMINAL` ends the run).
+- **validators** (`zu_checks.validators`) — `schema` (does the result fit the
+  requested shape?) and `grounding` (does every extracted value actually appear
+  in retrieved content? — the anti-hallucination check).
+
+They're packaged together because both are pure-stdlib (schema adds only
+`jsonschema`) and always present in the base — unlike the adapter packages
+(`zu-providers`, `zu-tools`, `zu-backends`), whose separation carries distinct
+heavy optional dependencies. All register via the standard `zu.detectors` /
+`zu.validators` entry-point groups, exactly as a third-party check would.

zu_checks-0.2.0/pyproject.toml

@@ -0,0 +1,44 @@
+[project]
+name = "zu-checks"
+version = "0.2.0"
+description = "Zu built-in checks: detectors (empty, error, js-shell, embedded-widget, bot-wall) + validators (schema, grounding)"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "Apache-2.0"
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Application Frameworks",
+    "Typing :: Typed",
+]
+# The built-in checks are pure-stdlib (+ jsonschema for the schema validator) and
+# always ship with the base runtime — they have no heavy/optional deps, which is
+# why detectors and validators live together here rather than as two packages.
+dependencies = ["zu-core==0.2.0", "jsonschema>=4"]
+
+[project.entry-points."zu.detectors"]
+empty = "zu_checks.detectors.empty:EmptyDetector"
+error = "zu_checks.detectors.error:ErrorDetector"
+js-shell = "zu_checks.detectors.js_shell:JsShellDetector"
+embedded-widget = "zu_checks.detectors.embedded_widget:EmbeddedWidgetDetector"
+bot-wall = "zu_checks.detectors.bot_wall:BotWallDetector"
+action-surface-blind = "zu_checks.detectors.action_surface_blind:ActionSurfaceBlindDetector"
+
+[project.entry-points."zu.validators"]
+schema = "zu_checks.validators.schema:SchemaValidator"
+grounding = "zu_checks.validators.grounding:GroundingValidator"
+
+[project.urls]
+Homepage = "https://github.com/k3-mt/zu"
+Repository = "https://github.com/k3-mt/zu"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/zu_checks"]

zu_checks-0.2.0/src/zu_checks/__init__.py

@@ -0,0 +1,13 @@
+"""Zu built-in checks — the two stdlib plugin kinds that ship with the base.
+
+* ``zu_checks.detectors`` — observation-time detectors whose Verdict severities
+  drive the loop (ESCALATE climbs the tier ladder; TERMINAL ends the run).
+* ``zu_checks.validators`` — on-final result checks (schema shape + grounding,
+  the anti-hallucination provenance check).
+
+They live in one package because both are pure-stdlib (the schema validator adds
+only ``jsonschema``) and always present in the base runtime — unlike the adapter
+packages (providers/tools/backends) whose separation carries distinct heavy
+optional dependencies. They register through the same ``zu.detectors`` /
+``zu.validators`` entry-point groups any third-party check would.
+"""

zu_checks-0.2.0/src/zu_checks/detectors/__init__.py

@@ -0,0 +1,37 @@
+"""Zu built-in detectors.
+
+A detector inspects an observation and may return a Verdict. Verdict
+severities (WARN, RETRY, ESCALATE, TERMINAL) map onto the loop's control flow:
+ESCALATE is the deterministic signal that climbs the tier ladder. Detectors
+are where escalation is decided — never improvised by the model.
+"""
+
+
+# What counts as page content in an observation, in preference order. The loop
+# stores a fetched/rendered page under one of these keys (mirrors zu_core.loop's
+# own ``_CONTENT_KEYS``); a detector must consult all of them or it goes blind to
+# a tool that returns ``{"text": ...}`` / ``{"content": ...}`` instead of html.
+# One source of truth, reused by ``empty`` too.
+_CONTENT_KEYS = ("html", "text", "content")
+
+
+def _html_of(ctx) -> str:
+    """Best-effort extraction of the page content from a RunContext observation.
+
+    Concatenates *every* present content key (html, text, content) rather than
+    returning only the first, so a marker detector is never blind to a tool that
+    splits content across keys — the same all-keys view the ``empty`` detector
+    uses, so the detectors agree on what "the content" is."""
+    obs = getattr(ctx, "observation", None)
+    if isinstance(obs, dict):
+        parts = [v for k in _CONTENT_KEYS if isinstance(v := obs.get(k), str) and v]
+        if parts:
+            return "\n".join(parts)
+    return ""
+
+
+def _contains_any(html: str, markers) -> bool:
+    """True if any marker (case-insensitive) appears in ``html`` — the shared
+    substring scan behind the marker-list detectors (bot-wall, js-shell)."""
+    lowered = html.lower()
+    return any(marker in lowered for marker in markers)

zu_checks-0.2.0/src/zu_checks/detectors/action_surface_blind.py

@@ -0,0 +1,33 @@
+"""action-surface-blind — escalate to vision when the action surface is blind.
+
+The Action Surface (Engineering Design §11) is a fast, cheap default for the
+common case; its competence boundary is the trigger for the next tier — pixels
+and a vision model. When the accessibility tree is too thin to trust, the tool
+sets ``surface_blind`` on its observation rather than silently returning an
+incomplete surface. This detector turns that signal into the deterministic
+ESCALATE that climbs the ladder to tier-4 vision (§11.4) — escalation decided by
+a detector, never improvised by the model.
+"""
+
+from __future__ import annotations
+
+from zu_core.ports import RunContext, Scope, Severity, Verdict
+
+
+class ActionSurfaceBlindDetector:
+    name = "action-surface-blind"
+    scope = Scope.PER_OBSERVATION
+
+    def inspect(self, ctx: RunContext) -> Verdict | None:
+        obs = getattr(ctx, "observation", None)
+        if not isinstance(obs, dict):
+            return None
+        if obs.get("surface_blind") is True:
+            surface = obs.get("action_surface")
+            reason = surface.get("blind_reason") if isinstance(surface, dict) else None
+            return Verdict(
+                severity=Severity.ESCALATE,
+                detector=self.name,
+                detail=reason or "action surface too thin to trust; escalate to vision",
+            )
+        return None

zu_checks-0.2.0/src/zu_checks/detectors/bot_wall.py

@@ -0,0 +1,54 @@
+"""bot-wall — fires on an anti-bot interstitial (Cloudflare, captcha, etc.)."""
+
+from __future__ import annotations
+
+from zu_core.ports import RunContext, Scope, Severity, Verdict
+
+from . import _contains_any, _html_of
+
+# Strong markers: phrasing characteristic of an anti-bot interstitial, specific
+# enough that their presence is treated as the signal on its own. This is a
+# deterministic heuristic, not a proof: a page that *discusses* CAPTCHAs (a news
+# story, this very comment) can contain "captcha" and would escalate — the cost
+# is a wasted tier-2 render, not a wrong answer, and escalating a borderline page
+# is the safer failure. ``cf-browser-verification`` is unambiguous; the natural-
+# language phrases are the ones with residual false-positive surface.
+_STRONG_MARKERS = (
+    "captcha",
+    "are you a robot",
+    "verify you are human",
+    "cf-browser-verification",
+)
+
+# Weak markers: real Cloudflare wall phrasing, but common-enough English that a
+# substring match alone false-positives (an article titled "Just a Moment in
+# History", a banner reading "Attention required"). They fire ONLY when a
+# Cloudflare fingerprint is also present, so a normal page is never escalated.
+_WEAK_MARKERS = (
+    "attention required",
+    "just a moment",
+)
+_CLOUDFLARE_FINGERPRINTS = (
+    "cloudflare",
+    "cf-ray",
+    "cf-browser-verification",
+    "__cf",
+    "/cdn-cgi/",
+)
+
+
+class BotWallDetector:
+    name = "bot-wall"
+    scope = Scope.PER_OBSERVATION
+
+    def inspect(self, ctx: RunContext) -> Verdict | None:
+        html = _html_of(ctx)
+        strong = _contains_any(html, _STRONG_MARKERS)
+        weak = _contains_any(html, _WEAK_MARKERS) and _contains_any(html, _CLOUDFLARE_FINGERPRINTS)
+        if strong or weak:
+            return Verdict(
+                severity=Severity.ESCALATE,
+                detector=self.name,
+                detail="anti-bot wall detected",
+            )
+        return None

zu_checks-0.2.0/src/zu_checks/detectors/embedded_widget.py

@@ -0,0 +1,97 @@
+"""embedded-widget — fires when the page's real content is inside a JS widget.
+
+The complement to ``js-shell``. ``js-shell`` catches an *empty* SPA shell (a
+``<div id="root">`` with no visible text). But a page can be full of human-visible
+chrome — nav, footer, copy — while the data the task actually needs (appointment
+slots, a price table, a seat map) is rendered by an **embedded third-party widget
+or iframe** that loads via JavaScript. A tier-1 ``http_fetch`` sees the chrome and
+the empty mount point, never the data, so it would loop forever or give up. This
+detector is the deterministic signal to *offer* the browser (tier 2) in that case.
+
+It is conservative about what counts as a content widget, to avoid escalating on
+ubiquitous analytics/ad scripts:
+
+* an ``<iframe>`` with an external ``http(s)`` ``src`` — an embedded application
+  whose content is not in this DOM; or
+* a **widget mount point** — an element whose *attributes* (id/class/data-*/domain)
+  name a content widget (``widget``, ``embed``, ``scheduler``, or a known booking
+  vendor) — together with an external ``<script>`` that fills it.
+
+ESCALATE only *unlocks* the browser; the model renders only if it still lacks the
+data, so being a touch generous here is cheap and fail-safe.
+"""
+
+from __future__ import annotations
+
+import re
+
+from zu_core.ports import RunContext, Scope, Severity, Verdict
+
+from . import _html_of
+
+# Tokens that, when they appear in an element's ATTRIBUTES (not visible text),
+# mark a JS content-widget mount. Generic structural words plus a few common
+# booking/scheduling vendors — kept to attribute context so a nav link like
+# href="/book-an-appointment" or body copy never trips it.
+_WIDGET_TOKENS = (
+    "widget", "embed", "scheduler", "data-widget",
+    "vetstoria", "oabp", "calendly", "acuityscheduling", "simplybook", "petsapp",
+)
+
+# An <iframe ...> carrying an external http(s) src — an embedded app.
+_IFRAME_SRC = re.compile(r"<iframe\b[^>]*\bsrc\s*=\s*[\"']https?://", re.IGNORECASE)
+# Any element's attribute span, to scan for a widget token in attribute context.
+_TAG_ATTRS = re.compile(r"<[a-zA-Z][a-zA-Z0-9]*\b([^>]*)>")
+# An external <script src="http(s)://..."> — the loader that fills a mount point.
+_EXTERNAL_SCRIPT = re.compile(r"<script\b[^>]*\bsrc\s*=\s*[\"']https?://", re.IGNORECASE)
+
+
+def _has_widget_mount(html: str) -> bool:
+    """True if some element's attributes name a content widget."""
+    for m in _TAG_ATTRS.finditer(html):
+        attrs = m.group(1).lower()
+        if any(tok in attrs for tok in _WIDGET_TOKENS):
+            return True
+    return False
+
+
+def _already_escalated(ctx: RunContext) -> bool:
+    """True if the run has already escalated (or browser-rendered) this run.
+
+    This detector is an escalation *trigger*: its job is to unlock the browser
+    tier once. After that it must go quiet — every later widget page (another
+    http_fetch, or the rendered DOM, which still carries the markers) would
+    otherwise re-fire, and at the top tier a re-escalation is 'exhausted' and ENDS
+    the run before the model can use the browser it just unlocked. So: fire once,
+    then defer to the model working at the higher tier."""
+    for ev in getattr(ctx, "events", []) or []:
+        et = getattr(ev, "type", "")
+        if et == "harness.task.escalated":
+            return True
+        if et == "data.source.fetched" and getattr(ev, "source", "") == "render_dom":
+            return True
+    return False
+
+
+class EmbeddedWidgetDetector:
+    name = "embedded-widget"
+    scope = Scope.PER_OBSERVATION
+
+    def inspect(self, ctx: RunContext) -> Verdict | None:
+        html = _html_of(ctx)
+        if not html:
+            return None
+        if _already_escalated(ctx):
+            return None  # already unlocked the browser; fire once, then stay quiet
+        embedded_app = bool(_IFRAME_SRC.search(html))
+        # A named mount point only counts when an external script is present to
+        # fill it — a bare class="...widget..." on a static page isn't deferred.
+        widget_loaded = _has_widget_mount(html) and bool(_EXTERNAL_SCRIPT.search(html))
+        if embedded_app or widget_loaded:
+            return Verdict(
+                severity=Severity.ESCALATE,
+                detector=self.name,
+                detail="page defers content to an embedded widget/iframe; "
+                       "escalate to a browser to render it",
+            )
+        return None

zu_checks-0.2.0/src/zu_checks/detectors/empty.py

@@ -0,0 +1,32 @@
+"""empty — fires when a *fetched page* carried no usable content.
+
+Scoped to page-content observations on purpose: it judges a fetch (a tool that
+returned ``html``/``text``/``content``) and escalates when that content is empty
+— the signal to climb to a browser. It must NOT fire on observations that are not
+page fetches — e.g. ``html_parse`` returning ``{"matches": [...]}`` (a successful
+extraction) or an error observation — or it would spuriously escalate after real
+work. So: a content key present but blank -> escalate; no content key -> not our
+concern (return None).
+"""
+
+from __future__ import annotations
+
+from zu_core.ports import RunContext, Scope, Severity, Verdict
+
+from . import _CONTENT_KEYS  # one source of truth for "what counts as page content"
+
+
+class EmptyDetector:
+    name = "empty"
+    scope = Scope.PER_OBSERVATION
+
+    def inspect(self, ctx: RunContext) -> Verdict | None:
+        obs = getattr(ctx, "observation", None)
+        if not isinstance(obs, dict):
+            return None
+        present = [k for k in _CONTENT_KEYS if k in obs]
+        if not present:
+            return None  # not a page-content observation — "empty" doesn't apply
+        if all(not str(obs.get(k) or "").strip() for k in present):
+            return Verdict(severity=Severity.ESCALATE, detector=self.name, detail="empty observation")
+        return None

zu_checks-0.2.0/src/zu_checks/detectors/error.py

@@ -0,0 +1,25 @@
+"""error — fires on an HTTP error status in the observation."""
+
+from __future__ import annotations
+
+from zu_core.ports import RunContext, Scope, Severity, Verdict
+
+
+class ErrorDetector:
+    name = "error"
+    scope = Scope.PER_OBSERVATION
+
+    def inspect(self, ctx: RunContext) -> Verdict | None:
+        # An HTTP error on a FETCHED page is RECOVERABLE, not fatal. A single bad
+        # url (a 403 WAF wall, a 404, a 5xx) says nothing about whether the RUN can
+        # succeed — an agent that searches and tries several candidates must be
+        # free to fetch the next one. Ending the whole run on one bad fetch (the
+        # old TERMINAL behaviour) broke exactly that. So this is RETRY: it is
+        # recorded and fed back, the model sees the error and chooses another
+        # action, and a run that genuinely cannot proceed still ends via the
+        # step/token budget — not by assuming the first url was the only one.
+        obs = getattr(ctx, "observation", None)
+        status = obs.get("status") if isinstance(obs, dict) else None
+        if isinstance(status, int) and status >= 400:
+            return Verdict(severity=Severity.RETRY, detector=self.name, detail=f"http {status}")
+        return None

zu_checks-0.2.0/src/zu_checks/detectors/js_shell.py

@@ -0,0 +1,75 @@
+"""js-shell — fires when a page is an empty JavaScript shell.
+
+The canonical escalation trigger: tier-1 http_fetch returns HTML that is
+essentially a <div id="root"></div> plus scripts, with no real text content.
+That is the signal to give up on the cheap tier and climb to a browser.
+
+The test is structural, not size-based: a page is a shell when it has a known
+SPA mount point *and* almost no human-visible text once scripts and styles are
+removed. Measuring visible text (rather than raw HTML length) is what step 5
+finalizes — a shell padded with a large inline bundle is still a shell, and a
+small page that happens to be real content is not escalated.
+"""
+
+from __future__ import annotations
+
+import re
+
+from zu_core.ports import RunContext, Scope, Severity, Verdict
+
+from . import _contains_any, _html_of
+
+# Common SPA mount points / framework markers.
+_SHELL_MARKERS = ('id="root"', "id='root'", 'id="app"', "id='app'", "__NEXT_DATA__")
+
+# Strip the elements whose contents are never visible text before measuring.
+# ``\s*`` in the close tag tolerates ``</script >``; the second pattern handles
+# an *unterminated* script/style — a browser treats everything after an unclosed
+# <script> as script text, so the heuristic does too (consume to end of input).
+# HTML comments are removed FIRST so a commented-out ``<!-- <script> -->`` (or
+# any literal ``<script`` inside a comment) can't trip the greedy _UNCLOSED rule
+# and erase the real article body after it — a deterministic false-positive the
+# unbalanced-tag heuristic would otherwise produce.
+_COMMENT = re.compile(r"<!--.*?-->", re.DOTALL)
+_NONVISIBLE = re.compile(r"<(script|style|template|noscript)\b.*?</\1\s*>", re.IGNORECASE | re.DOTALL)
+_UNCLOSED = re.compile(r"<(script|style|template|noscript)\b.*\Z", re.IGNORECASE | re.DOTALL)
+_TAGS = re.compile(r"<[^>]+>")
+_WS = re.compile(r"\s+")
+
+# Below this many characters of visible text, a page with a mount point is
+# treated as an unrendered shell. Tuned against the graded fixture set.
+_MIN_VISIBLE_TEXT = 64
+
+
+def _visible_text(html: str) -> str:
+    """Human-visible text: drop script/style/template/noscript bodies, strip
+    the remaining tags, and collapse whitespace."""
+    without_code = _COMMENT.sub(" ", html)
+    without_code = _NONVISIBLE.sub(" ", without_code)
+    without_code = _UNCLOSED.sub(" ", without_code)
+    text = _TAGS.sub(" ", without_code)
+    return _WS.sub(" ", text).strip()
+
+
+class JsShellDetector:
+    name = "js-shell"
+    scope = Scope.PER_OBSERVATION
+
+    def inspect(self, ctx: RunContext) -> Verdict | None:
+        html = _html_of(ctx)
+        if not html:
+            return None
+        lowered = html.lower()
+        looks_like_shell = _contains_any(html, _SHELL_MARKERS)
+        # The page defers its content to JS: a literal <script>, OR a module
+        # graph pulled in via <link rel="modulepreload"> with no inline script
+        # (a modern bundler shape the bare "<script" check would miss).
+        script_heavy = "<script" in lowered or "modulepreload" in lowered
+        thin = len(_visible_text(html)) < _MIN_VISIBLE_TEXT
+        if looks_like_shell and script_heavy and thin:
+            return Verdict(
+                severity=Severity.ESCALATE,
+                detector=self.name,
+                detail="page appears to be a JS shell; escalate to a browser",
+            )
+        return None

zu_checks-0.2.0/src/zu_checks/validators/__init__.py

@@ -0,0 +1,7 @@
+"""Zu built-in validators — the on-final checks of the result.
+
+The two cheapest rungs of the validation ladder: schema (does the result fit
+the requested shape?) and grounding (does every extracted value actually
+appear in retrieved content?). Grounding is the anti-hallucination check — the
+core of the "agents that actually work" claim.
+"""

zu_checks-0.2.0/src/zu_checks/validators/grounding.py

@@ -0,0 +1,162 @@
+"""grounding — every extracted value must appear in retrieved content.
+
+The anti-making-things-up check: a value the agent reports that is nowhere in
+the content the run actually fetched fails grounding. It reads the run's
+content from the event log via RunContext, so it proves provenance, not just
+plausibility.
+
+Matching is token-boundary-aware (build step 6): a value must appear in the
+retrieved content as a standalone token, not merely as a substring, so a short
+value such as ``"5"`` is not spuriously grounded by ``"1985"``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+
+from zu_core.contracts import Result
+from zu_core.ports import RunContext, Severity, Verdict
+
+
+def _normalize(s: str) -> str:
+    """Collapse whitespace and lowercase so trivial formatting differences
+    between an extracted value and the page text don't cause false failures."""
+    return " ".join(s.split()).lower()
+
+
+def _grounded(leaf_norm: str, corpus: str) -> bool:
+    """Is the normalized value present in the corpus on token boundaries?
+
+    Plain substring containment is too lenient: a short value like ``"5"`` would
+    match incidentally inside ``"1985"`` and let a fabricated number pass. We
+    require the value to appear as a standalone token, not a fragment of a longer
+    one, on two axes:
+
+    - **Alphanumeric flanks** (Unicode-aware via ``str.isalnum``): ``"5"`` inside
+      ``"1985"`` or ``"caf"`` inside ``"café"`` does not ground, while ``"$9.00"``
+      between ``>`` and ``<`` still does — punctuation is a boundary.
+    - **Number fragments across a decimal/thousands separator**: a ``.`` or ``,``
+      flanked by a digit on the *outer* side means the value is part of a larger
+      number, so ``"14"`` is not grounded by ``"3.14"`` nor ``"3"`` by ``"3.14"``
+      — but ``"5"`` in ``"Qty: 5."`` (the dot ends a sentence) still grounds.
+    """
+    if not leaf_norm:
+        # An empty normalized value has no provenance to prove, so it is NOT
+        # grounded — fail safe rather than free-pass. ``_leaf_strings`` already
+        # drops empty/whitespace leaves upstream, so this is reached only if a
+        # non-empty value normalizes to nothing; treating that as ungrounded
+        # keeps "I said nothing" from passing the anti-fabrication gate.
+        return False
+    n = len(leaf_norm)
+    start = 0
+    while True:
+        i = corpus.find(leaf_norm, start)
+        if i == -1:
+            return False
+        if _standalone(corpus, i, i + n):
+            return True
+        start = i + 1
+
+
+# Separators that join a number to more digits to form a single larger value or
+# a compound numeric token: decimal/thousands (``.`` ``,``) AND the connectors in
+# dates, versions, times, ranges, SKUs and phone numbers (``-`` ``/`` ``:``). A
+# match flanked by one of these with a digit on its *outer* side is a fragment of
+# a longer token, not a standalone value — so "12" is not grounded by "12-2024",
+# nor "30" by "12:30", just as "14" is not grounded by "3.14".
+_NUM_SEPARATORS = frozenset(".,-/:")
+
+
+def _standalone(corpus: str, lo: int, hi: int) -> bool:
+    """Are the chars flanking ``corpus[lo:hi]`` token boundaries, not part of a
+    longer alphanumeric token or a larger/compound number?"""
+    before = corpus[lo - 1] if lo > 0 else ""
+    after = corpus[hi] if hi < len(corpus) else ""
+    if before.isalnum() or after.isalnum():
+        return False
+    # A numeric separator adjacent to a digit on its outer side means this match
+    # is a slice of a larger number or compound token (e.g. "14" inside "3.14",
+    # "12" inside "12-2024", "30" inside "12:30").
+    if before in _NUM_SEPARATORS and corpus[lo - 2 : lo - 1].isdigit():
+        return False
+    if after in _NUM_SEPARATORS and corpus[hi + 1 : hi + 2].isdigit():
+        return False
+    return True
+
+
+def _leaf_strings(value: object) -> Iterator[str]:
+    """Yield every scalar leaf of a result value as a string to ground.
+
+    Numbers and booleans are real extracted values too — skipping non-strings
+    (the previous behaviour) let a fabricated price or count pass ungrounded.
+    bool is checked before int because ``isinstance(True, int)`` is True, and a
+    boolean is not groundable page text.
+    """
+    if isinstance(value, bool):
+        return
+    if isinstance(value, (str, int, float)):
+        text = str(value).strip()
+        if text:
+            yield text
+    elif isinstance(value, dict):
+        for v in value.values():
+            yield from _leaf_strings(v)
+    elif isinstance(value, (list, tuple)):
+        for v in value:
+            yield from _leaf_strings(v)
+
+
+def _retrieved_corpus(ctx: RunContext) -> str:
+    """Concatenate everything the run fetched, from data.source.fetched events.
+
+    Falls back to the current observation when the event log isn't populated
+    yet (the loop wires the full log in build step 4).
+    """
+    chunks: list[str] = []
+    for ev in getattr(ctx, "events", []) or []:
+        # Only *retrieved* content grounds a value — i.e. data.source.fetched
+        # events. Reading text-like keys from any event would let the model
+        # ground its own fabrications: harness.turn.completed carries the model's
+        # output text, which must never count as evidence about the page.
+        if getattr(ev, "type", "") != "data.source.fetched":
+            continue
+        payload = getattr(ev, "payload", {}) or {}
+        for key in ("html", "text", "content"):
+            if isinstance(payload.get(key), str):
+                chunks.append(payload[key])
+    # Fall back to the current observation ONLY when the event log has no fetched
+    # content yet (the loop wires the full log in build step 4). If fetched events
+    # exist, we must not also fold in the raw observation: an observation that is
+    # not itself retrieved page content (e.g. a model-produced turn that happens
+    # to carry a ``text`` key) would reopen the self-grounding hole the event-type
+    # filter above exists to close.
+    if not chunks:
+        obs = getattr(ctx, "observation", None)
+        if isinstance(obs, dict):
+            for key in ("html", "text", "content"):
+                if isinstance(obs.get(key), str):
+                    chunks.append(obs[key])
+    return "\n".join(chunks)
+
+
+class GroundingValidator:
+    name = "grounding"
+
+    def check(self, result: Result, ctx: RunContext) -> Verdict | None:
+        if not result.value:
+            return None
+        corpus = _normalize(_retrieved_corpus(ctx))
+        # The result value is usually a JSON object, but the schema may permit a
+        # non-object root (a list or scalar). Don't assume ``.items()`` — that
+        # would raise AttributeError and silently break the validator ladder.
+        value = result.value
+        fields = value.items() if isinstance(value, dict) else [("value", value)]
+        for field, field_value in fields:
+            for leaf in _leaf_strings(field_value):
+                if not _grounded(_normalize(leaf), corpus):
+                    return Verdict(
+                        severity=Severity.RETRY,
+                        detector=self.name,
+                        detail=f"value for {field!r} not found in retrieved content",
+                    )
+        return None

zu_checks-0.2.0/src/zu_checks/validators/schema.py

@@ -0,0 +1,41 @@
+"""schema — the result must satisfy the task's output JSON schema."""
+
+from __future__ import annotations
+
+import jsonschema
+
+from zu_core.contracts import Result
+from zu_core.ports import RunContext, Severity, Verdict
+
+
+class SchemaValidator:
+    name = "schema"
+
+    def check(self, result: Result, ctx: RunContext) -> Verdict | None:
+        schema = getattr(ctx.spec, "output_schema", None) or {}
+        if not schema:
+            return None  # nothing to check against
+        # jsonschema's richer errors carry a ``.message``; plain exceptions don't.
+        # One extraction, used by both the data-mismatch and bad-schema branches.
+        def message_of(e: Exception) -> str:
+            return getattr(e, "message", str(e))
+
+        try:
+            jsonschema.validate(instance=result.value, schema=schema)
+        except jsonschema.ValidationError as e:
+            # The data didn't match a valid schema — a retry might fix it.
+            return Verdict(severity=Severity.RETRY, detector=self.name, detail=message_of(e))
+        except Exception as e:  # noqa: BLE001 - a broken schema is terminal; see below
+            # The output_schema itself is unusable (comes from the TaskSpec,
+            # unvalidated): malformed (jsonschema.SchemaError), or an
+            # unresolvable ``$ref`` — which jsonschema raises as a *referencing*
+            # error that is NOT a subclass of SchemaError and would otherwise
+            # escape and crash the validation ladder. Retrying can't fix a broken
+            # schema, so any such error is terminal, caught here unconditionally
+            # so the ladder never sees an unhandled exception from a bad schema.
+            return Verdict(
+                severity=Severity.TERMINAL,
+                detector=self.name,
+                detail=f"invalid output_schema: {message_of(e)}",
+            )
+        return None

zu_checks-0.2.0/tests/test_detectors.py

@@ -0,0 +1,171 @@
+"""Smoke tests for the built-in detectors and their discovery.
+
+The escalation-ladder logic is finalized against the graded fixture set in
+build step 5; these lock the basic verdicts and the entry-point contract now.
+"""
+
+from __future__ import annotations
+
+from zu_checks.detectors.bot_wall import BotWallDetector
+from zu_checks.detectors.empty import EmptyDetector
+from zu_checks.detectors.error import ErrorDetector
+from zu_checks.detectors.js_shell import JsShellDetector
+from zu_core.ports import RunContext, Severity
+from zu_core.registry import Registry
+
+
+def _ctx(observation: dict) -> RunContext:
+    return RunContext(spec=None, observation=observation)
+
+
+def test_empty_fires_on_blank() -> None:
+    v = EmptyDetector().inspect(_ctx({"html": "   "}))
+    assert v is not None and v.severity is Severity.ESCALATE
+
+
+def test_empty_passes_on_content() -> None:
+    assert EmptyDetector().inspect(_ctx({"html": "<p>hi</p>"})) is None
+
+
+def test_empty_ignores_non_page_observations() -> None:
+    # Regression: a successful html_parse result (no content key) must NOT be
+    # read as an "empty page" and escalate — that misfired after real extraction.
+    assert EmptyDetector().inspect(_ctx({"selector": "h1", "matches": ["X"], "count": 1})) is None
+    assert EmptyDetector().inspect(_ctx({"error": "boom"})) is None
+    assert EmptyDetector().inspect(_ctx({})) is None
+
+
+def test_error_on_http_status_is_recoverable_not_terminal() -> None:
+    # An HTTP error on a fetched page is RETRY, never TERMINAL: a single bad url
+    # (403 WAF wall, 404, 410, 5xx, 429) must not end a run that can try another
+    # candidate. A truly stuck run ends via budget instead.
+    for status in (400, 403, 404, 405, 410, 429, 451, 500, 503):
+        v = ErrorDetector().inspect(_ctx({"status": status, "html": ""}))
+        assert v is not None and v.severity is Severity.RETRY, status
+
+
+def test_error_quiet_on_success() -> None:
+    assert ErrorDetector().inspect(_ctx({"status": 200, "html": "<p>ok</p>"})) is None
+
+
+def test_js_shell_fires_on_empty_spa() -> None:
+    html = '<html><body><div id="root"></div><script src="/app.js"></script></body></html>'
+    v = JsShellDetector().inspect(_ctx({"html": html}))
+    assert v is not None and v.severity is Severity.ESCALATE
+
+
+def test_js_shell_passes_on_real_content() -> None:
+    html = "<html><body>" + ("<p>real content here</p>" * 500) + "</body></html>"
+    assert JsShellDetector().inspect(_ctx({"html": html})) is None
+
+
+def test_js_shell_fires_despite_large_inline_script() -> None:
+    # A shell padded with a big inline bundle is still a shell: the visible-text
+    # test sees through the script, where a raw-length check would be fooled.
+    bundle = "var x=1;" * 2000  # ~16 KB of code, zero visible text
+    html = f'<html><body><div id="app"></div><script>{bundle}</script></body></html>'
+    v = JsShellDetector().inspect(_ctx({"html": html}))
+    assert v is not None and v.severity is Severity.ESCALATE
+
+
+def test_js_shell_fires_on_unterminated_script() -> None:
+    # Malformed/streamed HTML: a <script> that is never closed. A browser treats
+    # everything after it as script text, so the visible-text test must too —
+    # the page is still a shell, not real content.
+    html = '<html><body><div id="root"></div><script>var x=1;' + ("a();" * 2000)
+    v = JsShellDetector().inspect(_ctx({"html": html}))
+    assert v is not None and v.severity is Severity.ESCALATE
+
+
+def test_js_shell_passes_on_small_but_real_page() -> None:
+    # A mount point with genuine prose is rendered content, not a shell.
+    html = (
+        '<html><body><div id="root">'
+        "<h1>Acme Widget</h1><p>The finest widget, in stock and ready to ship today.</p>"
+        "</div><script src=/app.js></script></body></html>"
+    )
+    assert JsShellDetector().inspect(_ctx({"html": html})) is None
+
+
+def test_bot_wall_fires_on_captcha() -> None:
+    v = BotWallDetector().inspect(_ctx({"html": "<h1>Just a moment...</h1> please verify you are human"}))
+    assert v is not None and v.severity is Severity.ESCALATE
+
+
+def test_bot_wall_does_not_fire_on_innocent_phrase() -> None:
+    # A real article that happens to contain a weak phrase must NOT escalate
+    # without a corroborating Cloudflare fingerprint (regression: loose match).
+    page = _ctx({"html": "<article><h1>Just a moment in history</h1>"
+                          "<p>Attention required: read the safety notice first.</p></article>"})
+    assert BotWallDetector().inspect(page) is None
+
+
+def test_bot_wall_fires_on_weak_phrase_with_cloudflare_fingerprint() -> None:
+    page = _ctx({"html": "<title>Just a moment...</title>"
+                         "<div class='cf-browser-verification'></div><!-- cf-ray: abc -->"})
+    v = BotWallDetector().inspect(page)
+    assert v is not None and v.severity is Severity.ESCALATE
+
+
+# --- embedded-widget: content deferred to a JS widget/iframe -----------------
+
+_VETSTORIA = (
+    "<html><body><h1>Park Vets</h1><p>Lots of normal page chrome here, nav, "
+    "footer, plenty of visible text so this is NOT an empty shell.</p>"
+    "<div id='oabp-widget' domain='booking.vetstoria.com'></div>"
+    "<script src='https://booking.vetstoria.com/js/oabp-widget.js'></script>"
+    "</body></html>"
+)
+
+
+def test_embedded_widget_fires_on_a_js_booking_widget() -> None:
+    from zu_checks.detectors.embedded_widget import EmbeddedWidgetDetector
+
+    v = EmbeddedWidgetDetector().inspect(_ctx({"html": _VETSTORIA}))
+    assert v is not None and v.severity is Severity.ESCALATE
+
+
+def test_embedded_widget_fires_on_an_external_iframe_app() -> None:
+    from zu_checks.detectors.embedded_widget import EmbeddedWidgetDetector
+
+    html = "<html><body><p>book below</p><iframe src='https://book.example/app'></iframe></body></html>"
+    v = EmbeddedWidgetDetector().inspect(_ctx({"html": html}))
+    assert v is not None and v.severity is Severity.ESCALATE
+
+
+def test_embedded_widget_quiet_on_a_plain_content_page_with_analytics() -> None:
+    from zu_checks.detectors.embedded_widget import EmbeddedWidgetDetector
+
+    # A real content page that merely loads an external analytics script and links
+    # to a booking page must NOT escalate — the data is in the HTML.
+    html = (
+        "<html><body><h1>Opening hours</h1><p>Mon-Fri 9-5. Call 020 555 1234.</p>"
+        "<a href='/book-an-appointment'>Book an appointment</a>"
+        "<script src='https://www.googletagmanager.com/gtag/js'></script></body></html>"
+    )
+    assert EmbeddedWidgetDetector().inspect(_ctx({"html": html})) is None
+
+
+def test_embedded_widget_fires_once_then_stays_quiet() -> None:
+    # It's an escalation trigger: it unlocks the browser once, then must go quiet —
+    # a later widget page (or the rendered DOM) re-firing at the top tier would end
+    # the run as 'escalation exhausted' before the model can use the browser.
+    import types
+
+    from zu_checks.detectors.embedded_widget import EmbeddedWidgetDetector
+
+    det = EmbeddedWidgetDetector()
+    assert det.inspect(RunContext(spec=None, observation={"html": _VETSTORIA}, events=[])) is not None
+    for prior in (
+        types.SimpleNamespace(type="harness.task.escalated", source=None, payload={}),
+        types.SimpleNamespace(type="data.source.fetched", source="render_dom", payload={}),
+    ):
+        ctx = RunContext(spec=None, observation={"html": _VETSTORIA}, events=[prior])
+        assert det.inspect(ctx) is None
+
+
+def test_detectors_discoverable() -> None:
+    reg = Registry()
+    reg.discover()
+    for name in ("empty", "error", "js-shell", "embedded-widget", "bot-wall"):
+        assert name in reg.names("detectors")

zu_checks-0.2.0/tests/test_validators.py

@@ -0,0 +1,227 @@
+"""Tests for the built-in validators, their discovery, and their behaviour
+inside the loop (build step 6).
+
+These lock the core behaviour — schema enforcement and the anti-hallucination
+grounding check, including token-boundary precision — and prove grounding works
+against the real event log when run inside the interpreter loop (at finalise the
+observation is gone, so grounding must read the data.source.fetched events).
+"""
+
+from __future__ import annotations
+
+from zu_checks.validators.grounding import GroundingValidator
+from zu_checks.validators.schema import SchemaValidator
+from zu_core.bus import EventBus
+from zu_core.contracts import Result, Status, TaskSpec
+from zu_core.loop import run_task
+from zu_core.ports import RunContext, Severity
+from zu_core.registry import Registry
+from zu_providers.scripted import ScriptedProvider
+from zu_testing import fetch_tool
+
+_SCHEMA = {
+    "type": "object",
+    "properties": {"price": {"type": "string"}},
+    "required": ["price"],
+}
+
+
+def _ctx(observation: dict | None = None) -> RunContext:
+    spec = TaskSpec(query="extract the price", output_schema=_SCHEMA)
+    return RunContext(spec=spec, observation=observation)
+
+
+def test_schema_passes_valid_result() -> None:
+    r = Result(status=Status.SUCCESS, value={"price": "$9.00"})
+    assert SchemaValidator().check(r, _ctx()) is None
+
+
+def test_schema_fails_missing_required() -> None:
+    r = Result(status=Status.SUCCESS, value={})
+    v = SchemaValidator().check(r, _ctx())
+    # A plain data mismatch must be RETRY (the model can correct it) — NOT
+    # TERMINAL; the loop branches on this severity, so lock it, not just "fired".
+    assert v is not None and v.detector == "schema"
+    assert v.severity == Severity.RETRY
+
+
+def test_grounding_fails_invented_value() -> None:
+    r = Result(status=Status.SUCCESS, value={"price": "$1000.00"})
+    ctx = _ctx({"html": "<span class='price'>$9.00</span>"})
+    v = GroundingValidator().check(r, ctx)
+    assert v is not None and "not found" in (v.detail or "")
+
+
+def test_grounding_passes_value_on_page() -> None:
+    r = Result(status=Status.SUCCESS, value={"price": "$9.00"})
+    ctx = _ctx({"html": "<span class='price'>$9.00</span>"})
+    assert GroundingValidator().check(r, ctx) is None
+
+
+def test_grounding_checks_numeric_values() -> None:
+    # A fabricated *number* must not pass ungrounded (the old code skipped
+    # every non-string value, so invented prices/counts sailed through).
+    invented = Result(status=Status.SUCCESS, value={"stock": 4096})
+    ctx = _ctx({"html": "<span>in stock: 7</span>"})
+    assert GroundingValidator().check(invented, ctx) is not None
+
+    real = Result(status=Status.SUCCESS, value={"stock": 7})
+    assert GroundingValidator().check(real, ctx) is None
+
+
+def test_grounding_normalizes_whitespace() -> None:
+    # Whitespace/case differences between the value and the page shouldn't fail.
+    r = Result(status=Status.SUCCESS, value={"title": "Hello   World"})
+    ctx = _ctx({"html": "<h1>hello world</h1>"})
+    assert GroundingValidator().check(r, ctx) is None
+
+
+def test_grounding_rejects_short_value_inside_larger_token() -> None:
+    # Token-boundary precision: "5" must NOT be grounded by "1985" (plain
+    # substring matching would have let the fabricated rating pass).
+    only_in_year = _ctx({"html": "<p>The product launched in 1985.</p>"})
+    assert GroundingValidator().check(Result(status=Status.SUCCESS, value={"rating": 5}), only_in_year) is not None
+
+    # A genuinely standalone "5" on the page still grounds.
+    standalone = _ctx({"html": "<p>Rated 5 stars by 1985 reviewers.</p>"})
+    assert GroundingValidator().check(Result(status=Status.SUCCESS, value={"rating": 5}), standalone) is None
+
+
+def test_grounding_rejects_value_inside_a_decimal() -> None:
+    # A decimal point is a token boundary for *words*, but a fabricated number
+    # must not be grounded by a fragment of a larger number: "14" is not on a
+    # page that only says "$3.14", nor is "3".
+    page = _ctx({"html": "<span class='price'>$3.14</span>"})
+    assert GroundingValidator().check(Result(status=Status.SUCCESS, value={"n": 14}), page) is not None
+    assert GroundingValidator().check(Result(status=Status.SUCCESS, value={"n": 3}), page) is not None
+    # The whole decimal still grounds, and so does an integer the dot merely ends
+    # a sentence after (the dot is not flanked by a digit on its outer side).
+    assert GroundingValidator().check(Result(status=Status.SUCCESS, value={"p": "3.14"}), page) is None
+    qty = _ctx({"html": "<p>Qty: 5.</p>"})
+    assert GroundingValidator().check(Result(status=Status.SUCCESS, value={"q": 5}), qty) is None
+
+
+def test_grounding_rejects_value_inside_a_compound_token() -> None:
+    # A short number must not be grounded by a fragment of a date/version/time/
+    # SKU/phone joined by - / : — "12" is not on a page that only says "12-2024".
+    date = _ctx({"html": "<p>Released 12-2024 worldwide.</p>"})
+    assert GroundingValidator().check(Result(status=Status.SUCCESS, value={"m": 12}), date) is not None
+    ver = _ctx({"html": "<p>Build 4/19 shipped.</p>"})
+    assert GroundingValidator().check(Result(status=Status.SUCCESS, value={"b": 19}), ver) is not None
+    time = _ctx({"html": "<p>Starts at 12:30 sharp.</p>"})
+    assert GroundingValidator().check(Result(status=Status.SUCCESS, value={"t": 30}), time) is not None
+    # A genuinely standalone number flanked by a separator-with-no-adjacent-digit
+    # (e.g. a slash ending a path segment) still grounds.
+    path = _ctx({"html": "<a href='/items/42/'>item</a>"})
+    assert GroundingValidator().check(Result(status=Status.SUCCESS, value={"id": 42}), path) is None
+
+
+def test_grounding_is_unicode_token_aware() -> None:
+    # The flank check is Unicode-aware (str.isalnum), so a value is not grounded
+    # as a fragment of a non-ASCII word.
+    page = _ctx({"html": "<p>café société</p>"})
+    assert GroundingValidator().check(Result(status=Status.SUCCESS, value={"w": "caf"}), page) is not None
+    assert GroundingValidator().check(Result(status=Status.SUCCESS, value={"w": "café"}), page) is None
+
+
+def test_schema_error_is_terminal_not_a_crash() -> None:
+    # An invalid output_schema (from the TaskSpec) raises jsonschema.SchemaError
+    # internally; the validator must turn it into a TERMINAL verdict, never let
+    # it escape and crash the validation ladder.
+    spec = TaskSpec(query="x", output_schema={"type": "not-a-real-type"})
+    ctx = RunContext(spec=spec, observation=None)
+    r = Result(status=Status.SUCCESS, value={"a": 1})
+    v = SchemaValidator().check(r, ctx)
+    assert v is not None and v.severity == Severity.TERMINAL
+    assert "invalid output_schema" in (v.detail or "")
+
+
+def test_unresolvable_ref_is_terminal_not_a_crash() -> None:
+    # A schema with an unresolvable $ref raises a *referencing* error that is NOT
+    # a subclass of jsonschema.SchemaError — it would escape the old handlers and
+    # crash the ladder. It must become a TERMINAL verdict like any other broken
+    # schema, since the output_schema is untrusted TaskSpec input.
+    for bad in ({"$ref": "#/nope"}, {"$ref": "http://evil.example/x"}):
+        spec = TaskSpec(query="x", output_schema=bad)
+        ctx = RunContext(spec=spec, observation=None)
+        r = Result(status=Status.SUCCESS, value={"a": 1})
+        v = SchemaValidator().check(r, ctx)
+        assert v is not None and v.severity == Severity.TERMINAL
+        assert "invalid output_schema" in (v.detail or "")
+
+
+# --- grounding against the real event log, inside the loop -------------------
+
+_PAGE = "<html><body><span class='price'>$9.00</span></body></html>"
+
+
+def _loop_registry() -> Registry:
+    reg = Registry()
+    reg.register("tools", "http_fetch", fetch_tool(text=_PAGE))
+    reg.register("validators", "schema", SchemaValidator())
+    reg.register("validators", "grounding", GroundingValidator())
+    return reg
+
+
+async def test_grounding_in_loop_passes_value_from_event_log() -> None:
+    # At finalise the loop passes no observation, so grounding must read the
+    # price from the data.source.fetched event — the step-6 "against the event
+    # log" promise, end to end.
+    provider = ScriptedProvider.from_moves(
+        [
+            {"tool": "http_fetch", "args": {"url": "http://x.test/"}},
+            {"text": '{"price": "$9.00"}', "finish": "stop"},
+        ]
+    )
+    bus = EventBus()
+    result = await run_task(TaskSpec(query="price", output_schema=_SCHEMA), provider, _loop_registry(), bus)
+    assert result.status == Status.SUCCESS
+    assert result.value == {"price": "$9.00"}
+    types = [e.type for e in await bus.query()]
+    assert "data.source.fetched" in types  # grounding had the log to read
+    assert "harness.validation.failed" not in types
+
+
+async def test_grounding_in_loop_rejects_fabrication_then_accepts_correction() -> None:
+    # A price that is nowhere on the page fails grounding (RETRY); the loop feeds
+    # the failure back and the corrected, grounded value then succeeds.
+    provider = ScriptedProvider.from_moves(
+        [
+            {"tool": "http_fetch", "args": {"url": "http://x.test/"}},
+            {"text": '{"price": "$1000.00"}', "finish": "stop"},  # not on page -> RETRY
+            {"text": '{"price": "$9.00"}', "finish": "stop"},  # grounded -> SUCCESS
+        ]
+    )
+    bus = EventBus()
+    result = await run_task(TaskSpec(query="price", output_schema=_SCHEMA), provider, _loop_registry(), bus)
+    assert result.status == Status.SUCCESS
+    assert result.value == {"price": "$9.00"}
+    failed = [e for e in await bus.query() if e.type == "harness.validation.failed"]
+    assert failed and failed[0].payload["detector"] == "grounding"
+
+
+async def test_grounding_corpus_ignores_the_models_own_text() -> None:
+    # The model's output is recorded on harness.turn.completed (the live "train
+    # of thought"). Grounding must NOT treat that as retrieved content, or a model
+    # could ground a fabrication by simply emitting it. Only the fetched page
+    # (which here does NOT contain the price) counts — so the value fails.
+    provider = ScriptedProvider.from_moves(
+        [
+            {"tool": "http_fetch", "args": {"url": "http://x.test/"}},
+            {"text": '{"price": "$1000.00"}', "finish": "stop"},  # spoken, not on the page
+            {"text": '{"price": "$1000.00"}', "finish": "stop"},  # repeated — still ungrounded
+        ]
+    )
+    bus = EventBus()
+    result = await run_task(TaskSpec(query="price", output_schema=_SCHEMA), provider, _loop_registry(), bus)
+    # Never succeeds: the price is only ever in the model's own text, never the page.
+    assert result.status != Status.SUCCESS
+    failed = [e for e in await bus.query() if e.type == "harness.validation.failed"]
+    assert any(e.payload["detector"] == "grounding" for e in failed)
+
+
+def test_validators_discoverable() -> None:
+    reg = Registry()
+    reg.discover()
+    for name in ("schema", "grounding"):
+        assert name in reg.names("validators")