zu-patterns 0.2.2__tar.gz

zu_patterns-0.2.2/.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_patterns-0.2.2/PKG-INFO

@@ -0,0 +1,69 @@
+Metadata-Version: 2.4
+Name: zu-patterns
+Version: 0.2.2
+Summary: Zu pattern library: the policy-prior / move-ordering layer over the Action Surface (§5)
+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: zu-core==0.2.9
+Description-Content-Type: text/markdown
+
+# zu-patterns — the policy-prior / move-ordering layer (§5)
+
+A UI is a state space; the **Action Surface** is the move generator (affordances
+= legal moves). This package is the **policy prior + guided search** layer over
+that surface — the *AlphaZero* shape, not Deep Blue. It does **not** brute-force a
+live space (visiting a node might charge a card). It proposes the promising
+interaction *without* exploring, and the rail (§1) verifies the prediction.
+
+## The new port — `Pattern` (group `zu.patterns`)
+
+The `Pattern` Protocol lives in **zu-core** (`zu_core.ports.Pattern`), like the
+other ports. A pattern is **read-only**: it `recognize`s a situation over a core
+`SurfaceView` (`zu_core.surface`) and emits `success_invariants` /
+`failure_invariants` (declarative `zu_core.invariants.Invariant`s the rail
+verifies). It **never** calls a tool and **never** decides the task action — that
+is the policy's job. A recognized pattern is a **prior to be confirmed by
+observation, never ground truth** (ZU-RAIL-9): its success criteria compile (via
+`compile_spec`) to Monitors, and a behaviour mismatch fires a detector.
+
+The boundary that makes this clean: `recognize` takes the **core** `SurfaceView`,
+never zu-tools' `Surface`. zu-tools projects its `Surface` onto `SurfaceView`
+through a one-way adapter (`zu_tools.surface_adapter.to_surface_view`), so
+zu-patterns depends only on zu-core.
+
+## The pieces
+
+- `recognizer.py` — a pure pass over a `SurfaceView`: classify → archetype +
+  confidence. Low confidence ⇒ **no hint** (fall through to the model).
+- `reversibility.py` — a principled, default-to-committing classifier of an
+  action as **reversible** (read-only/idempotent, safe to explore live) vs
+  **committing** (side-effecting — the live-search/rail commit boundary). No
+  site-specific keyword blocklist: HTTP-method/idempotency, affordance semantics,
+  an extensible prior set, default-to-committing on uncertainty.
+- `rail.py` — the success/failure → `Invariant` helpers shared by the patterns.
+- `search.py` — an offline best-first planner **over the Phase-1
+  `zu_core.reachability.Fsm`** with the recognizer as the move-ordering prior,
+  plus an event-log → `Fsm` transition-model builder. Pure, offline, $0. The
+  live guided-MPC loop and the Shadow-sourced transition model are **deferred
+  seams** (stubbed/documented).
+
+## The 8 starter archetypes
+
+`cookie_banner`, `login_form`, `search_box`, `modal_dialog`, `paginated_list`,
+`sortable_table`, `autocomplete`, `cart_checkout` — the last is the canonical
+**irreversible-boundary** pattern (its place-order/pay step is classified
+COMMITTING; the script stops before it).
+
+All recognition is **deterministic** structural matching over roles/labels/states
+(no model), so every pattern is tested at $0 with hand-built `SurfaceView`s. A
+small-model recognizer is a future plugin behind the same Protocol.

zu_patterns-0.2.2/README.md

@@ -0,0 +1,50 @@
+# zu-patterns — the policy-prior / move-ordering layer (§5)
+
+A UI is a state space; the **Action Surface** is the move generator (affordances
+= legal moves). This package is the **policy prior + guided search** layer over
+that surface — the *AlphaZero* shape, not Deep Blue. It does **not** brute-force a
+live space (visiting a node might charge a card). It proposes the promising
+interaction *without* exploring, and the rail (§1) verifies the prediction.
+
+## The new port — `Pattern` (group `zu.patterns`)
+
+The `Pattern` Protocol lives in **zu-core** (`zu_core.ports.Pattern`), like the
+other ports. A pattern is **read-only**: it `recognize`s a situation over a core
+`SurfaceView` (`zu_core.surface`) and emits `success_invariants` /
+`failure_invariants` (declarative `zu_core.invariants.Invariant`s the rail
+verifies). It **never** calls a tool and **never** decides the task action — that
+is the policy's job. A recognized pattern is a **prior to be confirmed by
+observation, never ground truth** (ZU-RAIL-9): its success criteria compile (via
+`compile_spec`) to Monitors, and a behaviour mismatch fires a detector.
+
+The boundary that makes this clean: `recognize` takes the **core** `SurfaceView`,
+never zu-tools' `Surface`. zu-tools projects its `Surface` onto `SurfaceView`
+through a one-way adapter (`zu_tools.surface_adapter.to_surface_view`), so
+zu-patterns depends only on zu-core.
+
+## The pieces
+
+- `recognizer.py` — a pure pass over a `SurfaceView`: classify → archetype +
+  confidence. Low confidence ⇒ **no hint** (fall through to the model).
+- `reversibility.py` — a principled, default-to-committing classifier of an
+  action as **reversible** (read-only/idempotent, safe to explore live) vs
+  **committing** (side-effecting — the live-search/rail commit boundary). No
+  site-specific keyword blocklist: HTTP-method/idempotency, affordance semantics,
+  an extensible prior set, default-to-committing on uncertainty.
+- `rail.py` — the success/failure → `Invariant` helpers shared by the patterns.
+- `search.py` — an offline best-first planner **over the Phase-1
+  `zu_core.reachability.Fsm`** with the recognizer as the move-ordering prior,
+  plus an event-log → `Fsm` transition-model builder. Pure, offline, $0. The
+  live guided-MPC loop and the Shadow-sourced transition model are **deferred
+  seams** (stubbed/documented).
+
+## The 8 starter archetypes
+
+`cookie_banner`, `login_form`, `search_box`, `modal_dialog`, `paginated_list`,
+`sortable_table`, `autocomplete`, `cart_checkout` — the last is the canonical
+**irreversible-boundary** pattern (its place-order/pay step is classified
+COMMITTING; the script stops before it).
+
+All recognition is **deterministic** structural matching over roles/labels/states
+(no model), so every pattern is tested at $0 with hand-built `SurfaceView`s. A
+small-model recognizer is a future plugin behind the same Protocol.

zu_patterns-0.2.2/pyproject.toml

@@ -0,0 +1,42 @@
+[project]
+name = "zu-patterns"
+version = "0.2.2"
+description = "Zu pattern library: the policy-prior / move-ordering layer over the Action Surface (§5)"
+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 boundary holds: zu-patterns speaks ONLY the core SurfaceView — it depends
+# on zu-core and NOT on zu-tools. A pattern recognizes over the core type; the
+# zu-tools Surface → SurfaceView projection lives in zu-tools, one-way.
+dependencies = ["zu-core==0.2.9"]
+
+[project.entry-points."zu.patterns"]   # <- how a pattern is registered (§5)
+cookie_banner = "zu_patterns.cookie_banner:CookieBanner"
+login_form = "zu_patterns.login_form:LoginForm"
+search_box = "zu_patterns.search_box:SearchBox"
+modal_dialog = "zu_patterns.modal_dialog:ModalDialog"
+paginated_list = "zu_patterns.paginated_list:PaginatedList"
+sortable_table = "zu_patterns.sortable_table:SortableTable"
+autocomplete = "zu_patterns.autocomplete:Autocomplete"
+cart_checkout = "zu_patterns.cart_checkout:CartCheckout"
+
+[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_patterns"]

zu_patterns-0.2.2/src/zu_patterns/__init__.py

@@ -0,0 +1,53 @@
+"""zu-patterns — the policy-prior / move-ordering layer over the Action Surface.
+
+The ``Pattern`` port itself lives in zu-core (``zu_core.ports.Pattern``); this
+package ships the built-in patterns, the recognizer pass, the reversible-vs-
+committing classifier, and the offline guided search over the Phase-1 FSM.
+"""
+
+from __future__ import annotations
+
+from .recognizer import Recognition, recognize
+from .reversibility import (
+    DEFAULT_PRIORS,
+    ActionPrior,
+    Commitment,
+    Signal,
+    classify_action,
+)
+from .search import (
+    Candidate,
+    MpcDecision,
+    MpcOutcome,
+    Plan,
+    PlanStep,
+    fsm_from_events,
+    fsm_from_shadow,
+    fsm_from_shadow_events,
+    live_mpc_step,
+    merge_transition_models,
+    mpc_run,
+    plan,
+)
+
+__all__ = [
+    "Recognition",
+    "recognize",
+    "Commitment",
+    "Signal",
+    "ActionPrior",
+    "DEFAULT_PRIORS",
+    "classify_action",
+    "Plan",
+    "PlanStep",
+    "fsm_from_events",
+    "plan",
+    "live_mpc_step",
+    "mpc_run",
+    "Candidate",
+    "MpcDecision",
+    "MpcOutcome",
+    "fsm_from_shadow",
+    "fsm_from_shadow_events",
+    "merge_transition_models",
+]

zu_patterns-0.2.2/src/zu_patterns/_match.py

@@ -0,0 +1,80 @@
+"""Shared, purely-structural matching helpers for the built-in patterns.
+
+These are deterministic predicates over a core ``SurfaceView``'s affordances —
+roles, normalized labels, states. No model, no site constants: a pattern derives
+its ``label_hint`` from the surface it matched, never from a hardcoded magic
+string. The token lists below (``user``/``password``/``search``/``accept`` …) are
+GENERIC, language-of-the-archetype vocabulary — the same way an accessibility
+checker knows ``button`` means "actionable" — not site-specific keys.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from zu_core.surface import SurfaceAffordance, SurfaceView
+
+
+def norm(s: str) -> str:
+    """Lowercase, collapse whitespace — the canonical form for label matching."""
+    return " ".join(s.lower().split())
+
+
+def label_has(aff: SurfaceAffordance, tokens: Iterable[str]) -> bool:
+    """True iff the affordance's normalized label contains any token."""
+    lbl = norm(aff.label)
+    return any(t in lbl for t in tokens)
+
+
+def has_state(aff: SurfaceAffordance, *states: str) -> bool:
+    sset = {norm(s) for s in aff.states}
+    return any(norm(s) in sset for s in states)
+
+
+def of_role(surface: SurfaceView, *roles: str) -> list[SurfaceAffordance]:
+    rset = {r.lower() for r in roles}
+    return [a for a in surface.affordances if a.role.lower() in rset]
+
+
+def first(
+    surface: SurfaceView,
+    *,
+    roles: Iterable[str] = (),
+    tokens: Iterable[str] = (),
+    states: Iterable[str] = (),
+) -> SurfaceAffordance | None:
+    """The first affordance matching ALL of the supplied predicates (any omitted
+    predicate is satisfied vacuously)."""
+    rset = {r.lower() for r in roles}
+    tlist = list(tokens)
+    slist = list(states)
+    for a in surface.affordances:
+        if rset and a.role.lower() not in rset:
+            continue
+        if tlist and not label_has(a, tlist):
+            continue
+        if slist and not has_state(a, *slist):
+            continue
+        return a
+    return None
+
+
+def context_has(surface: SurfaceView, tokens: Iterable[str]) -> bool:
+    blob = norm(" ".join(surface.context))
+    return any(t in blob for t in tokens)
+
+
+# Generic archetype vocabularies (NOT site constants).
+USER_TOKENS = ("user", "email", "e-mail", "login", "username", "account name")
+PASSWORD_TOKENS = ("password", "passcode", "pass word")
+SUBMIT_TOKENS = ("sign in", "log in", "login", "submit", "continue", "next", "go")
+SEARCH_TOKENS = ("search", "find", "query", "look up")
+ACCEPT_TOKENS = ("accept", "agree", "allow", "got it", "ok", "i accept", "consent")
+REJECT_TOKENS = ("reject", "decline", "deny", "refuse", "no thanks")
+CLOSE_TOKENS = ("close", "dismiss", "×", "x")
+CONFIRM_TOKENS = ("confirm", "yes", "ok", "proceed", "continue")
+NEXT_TOKENS = ("next", "next page", ">", "more", "load more")
+PREV_TOKENS = ("prev", "previous", "back", "<")
+CART_TOKENS = ("add to cart", "add to bag", "add to basket")
+CHECKOUT_TOKENS = ("checkout", "check out")
+PLACE_ORDER_TOKENS = ("place order", "buy now", "pay", "complete purchase", "confirm order")

zu_patterns-0.2.2/src/zu_patterns/autocomplete.py

@@ -0,0 +1,62 @@
+"""autocomplete — a textbox/combobox (expanded / controls a listbox of options).
+
+Script: fill partial, pick option. Typing + picking is REVERSIBLE (it fills a
+field). Success: the option fills the field.
+"""
+
+from __future__ import annotations
+
+from zu_core.invariants import Invariant
+from zu_core.ports import PatternStep, RecognitionResult
+from zu_core.surface import SurfaceView
+
+from . import _match as m
+from .rail import surface_shows
+
+_EXPAND_STATES = ("expanded", "haspopup", "autocomplete")
+
+
+class Autocomplete:
+    name = "autocomplete"
+    archetype = "autocomplete"
+
+    def recognize(self, surface: SurfaceView) -> RecognitionResult | None:
+        box = next(
+            (
+                a
+                for a in surface.affordances
+                if a.role.lower() in {"combobox", "textbox", "searchbox"}
+                and m.has_state(a, *_EXPAND_STATES)
+            ),
+            None,
+        )
+        if box is None:
+            return None
+        options = m.of_role(surface, "option")
+        # An expanded combobox with options present is the strong case.
+        confidence = 0.85 if options else 0.62
+        script = [PatternStep(op="fill", role=box.role, label_hint=m.norm(box.label), note="type")]
+        handles = [box.handle]
+        if options:
+            opt = options[0]
+            script.append(
+                PatternStep(op="select", role="option", label_hint=m.norm(opt.label), note="pick")
+            )
+            handles.append(opt.handle)
+        return RecognitionResult(
+            archetype=self.archetype,
+            confidence=confidence,
+            matched_handles=tuple(handles),
+            script=tuple(script),
+            detail="autocomplete",
+        )
+
+    def success_invariants(self, result: RecognitionResult) -> list[Invariant]:
+        handle = result.matched_handles[0] if result.matched_handles else None
+        # Done = the field EVENTUALLY present (filled) by the deadline.
+        return [surface_shows(self.archetype, "option_filled", handle=handle, liveness=True)]
+
+    def failure_invariants(self, result: RecognitionResult) -> list[Invariant]:
+        # Failure CONTEXT = a "no results" empty-state appears. Safety shape:
+        # THROUGHOUT NOT contains(no results) — fires the instant it lands.
+        return [surface_shows(self.archetype, "no_options", label="no results", negate=True)]

zu_patterns-0.2.2/src/zu_patterns/cart_checkout.py

@@ -0,0 +1,102 @@
+"""cart_checkout — the canonical IRREVERSIBLE-BOUNDARY pattern.
+
+Recognizes a button cluster {add to cart, checkout, place order, pay} alongside
+line-item context. The proposed script STOPS BEFORE the committing step: it adds
+to cart / proceeds to checkout, but the place-order/pay step is classified
+COMMITTING — the live-search and rail commit boundary. This is the discipline
+made into a pattern: search may explore up to the boundary, never auto-cross it.
+Success: an order-confirmation surface. The place-order step never auto-executes.
+"""
+
+from __future__ import annotations
+
+from zu_core.invariants import Invariant
+from zu_core.ports import PatternStep, RecognitionResult
+from zu_core.surface import SurfaceView
+
+from . import _match as m
+from .rail import surface_shows
+from .reversibility import ActionPrior, Commitment
+
+_LINE_ITEM_CONTEXT = ("cart", "basket", "bag", "subtotal", "order summary", "line item", "qty")
+_CONFIRM_CONTEXT = ("order confirmed", "thank you for your order", "order number", "confirmation")
+
+
+class CartCheckout:
+    name = "cart_checkout"
+    archetype = "cart_checkout"
+
+    def recognize(self, surface: SurfaceView) -> RecognitionResult | None:
+        add = m.first(surface, roles=("button",), tokens=m.CART_TOKENS)
+        checkout = m.first(surface, roles=("button", "link"), tokens=m.CHECKOUT_TOKENS)
+        place = m.first(surface, roles=("button",), tokens=m.PLACE_ORDER_TOKENS)
+        if add is None and checkout is None and place is None:
+            return None
+        line_ctx = m.context_has(surface, _LINE_ITEM_CONTEXT)
+        # Confidence: a cart/checkout button WITH line-item context is strong.
+        present = [x for x in (add, checkout, place) if x is not None]
+        confidence = 0.85 if (line_ctx and present) else 0.6
+        # The proposed script advances toward — but STOPS BEFORE — the committing
+        # place-order/pay step. We propose the safe step (add / go to checkout) and
+        # mark the committing step with an ``expect`` (a boundary marker), never a
+        # ``submit`` the search would auto-cross.
+        script: list[PatternStep] = []
+        handles: list[str] = []
+        safe = add or checkout
+        if safe is not None:
+            script.append(
+                PatternStep(op="click", role=safe.role, label_hint=m.norm(safe.label), note="proceed")
+            )
+            handles.append(safe.handle)
+        if place is not None:
+            # The boundary: marked, not proposed for execution.
+            script.append(
+                PatternStep(
+                    op="expect",
+                    role="button",
+                    label_hint=m.norm(place.label),
+                    note="COMMIT BOUNDARY: place-order/pay is committing — do not auto-cross",
+                )
+            )
+            handles.append(place.handle)
+        return RecognitionResult(
+            archetype=self.archetype,
+            confidence=confidence,
+            matched_handles=tuple(handles),
+            script=tuple(script),
+            detail="cart/checkout (irreversible boundary)",
+        )
+
+    def success_invariants(self, result: RecognitionResult) -> list[Invariant]:
+        # Done = an order-confirmation surface EVENTUALLY appears (by the deadline).
+        # A committed-but-never-confirmed run violates this liveness at the deadline.
+        return [
+            surface_shows(self.archetype, "order_confirmed", label="order confirmed", liveness=True)
+        ]
+
+    def failure_invariants(self, result: RecognitionResult) -> list[Invariant]:
+        # Failure CONTEXT = a payment/checkout error appears. Safety shape:
+        # THROUGHOUT NOT contains(error) — fires the instant the error lands.
+        return [surface_shows(self.archetype, "checkout_error", label="error", negate=True)]
+
+    # The reversibility prior this pattern CONTRIBUTES: its place-order/pay step is
+    # COMMITTING. A planner/classifier passes this into ``classify_action`` so the
+    # boundary is declared by the pattern, not hardcoded into the core classifier.
+    @staticmethod
+    def commit_prior() -> ActionPrior:
+        def _is_place_order(facts: dict) -> bool:
+            note = str(facts.get("note", "")).lower()
+            op = str(facts.get("op", "")).lower()
+            label = str(facts.get("label_hint", "")).lower()
+            return (
+                op in {"place_order", "pay", "purchase", "checkout"}
+                or "commit boundary" in note
+                or any(tok in label for tok in m.PLACE_ORDER_TOKENS)
+            )
+
+        return ActionPrior(
+            name="cart_checkout.place_order",
+            matcher=_is_place_order,
+            commitment=Commitment.COMMITTING,
+            weight=2.0,
+        )

zu_patterns-0.2.2/src/zu_patterns/cookie_banner.py

@@ -0,0 +1,71 @@
+"""cookie_banner — a consent/cookie banner with an accept/reject button cluster.
+
+Recognized when the surface's context mentions cookies/consent (or an
+alert/region carries it) and the affordances are dominated by accept/agree/reject
+buttons with no other task affordances. Dismissing is idempotent ⇒ REVERSIBLE.
+Success: the accept button is GONE from the next surface (a negated
+SURFACE_CONTAINS). Failure: the banner persists.
+"""
+
+from __future__ import annotations
+
+from zu_core.invariants import Invariant
+from zu_core.ports import PatternStep, RecognitionResult
+from zu_core.surface import SurfaceView
+
+from . import _match as m
+from .rail import surface_shows
+
+_CONSENT_CONTEXT = ("cookie", "consent", "gdpr", "privacy", "tracking")
+
+
+class CookieBanner:
+    name = "cookie_banner"
+    archetype = "cookie_banner"
+
+    def recognize(self, surface: SurfaceView) -> RecognitionResult | None:
+        accept = m.first(surface, roles=("button",), tokens=m.ACCEPT_TOKENS)
+        if accept is None:
+            return None
+        buttons = m.of_role(surface, "button")
+        consent_ctx = m.context_has(surface, _CONSENT_CONTEXT)
+        consent_label = any(m.label_has(b, _CONSENT_CONTEXT) for b in buttons)
+        if not (consent_ctx or consent_label):
+            return None
+        # Confidence: a small banner (few affordances) dominated by accept/reject
+        # is a strong match; a page with many other affordances is weaker.
+        non_consent = [
+            a
+            for a in surface.affordances
+            if a.handle != accept.handle
+            and not m.label_has(a, m.ACCEPT_TOKENS + m.REJECT_TOKENS + m.CLOSE_TOKENS)
+        ]
+        confidence = 0.9 if len(non_consent) <= 1 else 0.65
+        if consent_ctx and consent_label:
+            confidence = min(1.0, confidence + 0.05)
+        return RecognitionResult(
+            archetype=self.archetype,
+            confidence=confidence,
+            matched_handles=(accept.handle,),
+            script=(
+                PatternStep(
+                    op="click", role="button", label_hint=m.norm(accept.label), note="accept"
+                ),
+            ),
+            detail="consent banner",
+        )
+
+    def success_invariants(self, result: RecognitionResult) -> list[Invariant]:
+        handle = result.matched_handles[0] if result.matched_handles else None
+        # Done = the accept button is EVENTUALLY gone (a liveness-of-ABSENCE check:
+        # the banner is present pre-dismiss, so it must not fire until the deadline;
+        # if the button never goes away by the deadline, that liveness VIOLATES —
+        # which IS the "banner persists" failure, captured without a redundant
+        # positive must-contain-THROUGHOUT invariant).
+        return [surface_shows(self.archetype, "dismissed", handle=handle, negate=True, liveness=True)]
+
+    def failure_invariants(self, result: RecognitionResult) -> list[Invariant]:
+        # Failure CONTEXT = a consent-wall error appears. Safety shape: THROUGHOUT
+        # NOT contains(error) — fires the instant it lands. (The "banner persists"
+        # mode is the success liveness deadline-violation, not duplicated here.)
+        return [surface_shows(self.archetype, "consent_error", label="error", negate=True)]