zu-patterns 0.2.2__py3-none-any.whl

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/_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/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/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/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)]

zu_patterns/login_form.py

@@ -0,0 +1,87 @@
+"""login_form — a username/email textbox + a password textbox + a submit button.
+
+Script (a PROPOSAL, never auto-run): fill user, fill password, click submit.
+Submit is COMMITTING (a form POST). Success: a post-submit surface shows an
+account/logout/profile affordance. Failure: an error alert/status appears.
+"""
+
+from __future__ import annotations
+
+from zu_core import events as ev
+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
+
+_ACCOUNT_TOKENS = ("logout", "log out", "sign out", "account", "profile", "my account")
+_ERROR_TOKENS = ("invalid", "incorrect", "error", "wrong password", "failed", "try again")
+
+
+class LoginForm:
+    name = "login_form"
+    archetype = "login_form"
+
+    def recognize(self, surface: SurfaceView) -> RecognitionResult | None:
+        user = m.first(surface, roles=("textbox", "searchbox"), tokens=m.USER_TOKENS)
+        # A password field is a textbox carrying a 'password' state, or labelled so.
+        pw = next(
+            (
+                a
+                for a in m.of_role(surface, "textbox")
+                if m.has_state(a, "password") or m.label_has(a, m.PASSWORD_TOKENS)
+            ),
+            None,
+        )
+        submit = m.first(surface, roles=("button",), tokens=m.SUBMIT_TOKENS)
+        if user is None or pw is None:
+            return None
+        # Confidence rises with a submit button present and a password state.
+        confidence = 0.7
+        if submit is not None:
+            confidence += 0.15
+        if m.has_state(pw, "password"):
+            confidence += 0.1
+        confidence = min(1.0, confidence)
+        handles = tuple(h for h in (user.handle, pw.handle, submit.handle if submit else None) if h)
+        script = [
+            PatternStep(op="fill", role="textbox", label_hint=m.norm(user.label), note="username"),
+            PatternStep(op="fill", role="textbox", label_hint=m.norm(pw.label), note="password"),
+        ]
+        if submit is not None:
+            script.append(
+                PatternStep(
+                    op="submit", role="button", label_hint=m.norm(submit.label), note="commit"
+                )
+            )
+        return RecognitionResult(
+            archetype=self.archetype,
+            confidence=confidence,
+            matched_handles=handles,
+            script=tuple(script),
+            detail="login form",
+        )
+
+    def success_invariants(self, result: RecognitionResult) -> list[Invariant]:
+        # Done = a post-submit surface EVENTUALLY shows an account/logout
+        # affordance (a liveness-by-deadline postcondition: absent until the submit
+        # completes, so it must NOT fire on the pre-submit login surface).
+        return [
+            surface_shows(self.archetype, "reached_account", label=tok, liveness=True)
+            for tok in ("Logout", "Sign out", "Account")
+        ][:1]
+
+    def failure_invariants(self, result: RecognitionResult) -> list[Invariant]:
+        # Failure CONTEXT = an error alert/status appeared. Correct safety shape:
+        # "THROUGHOUT: NOT contains(error)" — the Monitor fires the instant an
+        # error context lands; the pre-interaction surface (no error) satisfies it.
+        return [
+            surface_shows(
+                self.archetype,
+                "error_alert",
+                label="error",
+                event_type=ev.SURFACE_CAPTURED,
+                negate=True,
+            )
+        ]

zu_patterns/modal_dialog.py

@@ -0,0 +1,64 @@
+"""modal_dialog — an alertdialog/dialog trapping focus with a close/confirm.
+
+Reversible when the proposed step is a close/dismiss; COMMITTING when it is a
+confirm/proceed (a confirm may commit an action). Success: the dialog is gone.
+"""
+
+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
+
+_DIALOG_CONTEXT = ("dialog", "modal", "are you sure", "please confirm")
+
+
+class ModalDialog:
+    name = "modal_dialog"
+    archetype = "modal_dialog"
+
+    def recognize(self, surface: SurfaceView) -> RecognitionResult | None:
+        # A dialog surfaces as a close button and/or a confirm button, with
+        # dialog-ish context. (Cookie banners are their own pattern and rank
+        # higher via consent vocabulary; this is the generic modal.)
+        close = m.first(surface, roles=("button",), tokens=m.CLOSE_TOKENS)
+        confirm = m.first(surface, roles=("button",), tokens=m.CONFIRM_TOKENS)
+        if close is None and confirm is None:
+            return None
+        dialogish = m.context_has(surface, _DIALOG_CONTEXT)
+        # Avoid stealing the cookie-banner case: if it reads as consent, defer.
+        if m.context_has(surface, ("cookie", "consent")):
+            return None
+        if not dialogish and close is None:
+            return None
+        chosen = close or confirm
+        assert chosen is not None
+        # Prefer the reversible close step in the proposed script.
+        op = "click" if chosen is close else "confirm"
+        confidence = 0.8 if dialogish else 0.6
+        return RecognitionResult(
+            archetype=self.archetype,
+            confidence=confidence,
+            matched_handles=(chosen.handle,),
+            script=(
+                PatternStep(op=op, role="button", label_hint=m.norm(chosen.label), note="dismiss"),
+            ),
+            detail="modal dialog",
+        )
+
+    def success_invariants(self, result: RecognitionResult) -> list[Invariant]:
+        handle = result.matched_handles[0] if result.matched_handles else None
+        # Done = the dialog is EVENTUALLY gone (liveness-of-ABSENCE: the dialog is
+        # present pre-dismiss, so it must not fire until the deadline; a dialog that
+        # never closes by the deadline VIOLATES this liveness — the "persists"
+        # failure, captured without a redundant positive must-contain-THROUGHOUT).
+        return [surface_shows(self.archetype, "dismissed", handle=handle, negate=True, liveness=True)]
+
+    def failure_invariants(self, result: RecognitionResult) -> list[Invariant]:
+        # Failure CONTEXT = an error appears inside/after the dialog. Safety shape:
+        # THROUGHOUT NOT contains(error) — fires the instant it lands. (The
+        # "persists" mode is the success liveness deadline-violation, not duplicated.)
+        return [surface_shows(self.archetype, "dialog_error", label="error", negate=True)]

zu_patterns/paginated_list.py

@@ -0,0 +1,52 @@
+"""paginated_list — a list/listbox plus a next/prev/page-N link cluster.
+
+Script: click next. Navigation ⇒ REVERSIBLE. Success: the list refreshes / the
+page context advances.
+"""
+
+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
+
+
+class PaginatedList:
+    name = "paginated_list"
+    archetype = "paginated_list"
+
+    def recognize(self, surface: SurfaceView) -> RecognitionResult | None:
+        has_list = bool(m.of_role(surface, "list", "listbox", "table", "grid"))
+        # A 'next' affordance is a link or a button labelled next/more.
+        nxt = m.first(surface, roles=("link", "button"), tokens=m.NEXT_TOKENS)
+        prev = m.first(surface, roles=("link", "button"), tokens=m.PREV_TOKENS)
+        if nxt is None and prev is None:
+            return None
+        # Pagination is strongest with a list AND a next control.
+        confidence = 0.8 if (has_list and nxt is not None) else 0.6
+        target = nxt or prev
+        assert target is not None
+        return RecognitionResult(
+            archetype=self.archetype,
+            confidence=confidence,
+            matched_handles=(target.handle,),
+            script=(
+                PatternStep(
+                    op="click", role=target.role, label_hint=m.norm(target.label), note="paginate"
+                ),
+            ),
+            detail="paginated list",
+        )
+
+    def success_invariants(self, result: RecognitionResult) -> list[Invariant]:
+        # Done = a fresh list surface EVENTUALLY appears (a results/list affordance
+        # present by the deadline). Liveness, not THROUGHOUT.
+        return [surface_shows(self.archetype, "page_advanced", label="results", liveness=True)]
+
+    def failure_invariants(self, result: RecognitionResult) -> list[Invariant]:
+        # Failure CONTEXT = an error/empty-state banner appears (navigation broke).
+        # Safety shape: THROUGHOUT NOT contains(error) — fires when it lands.
+        return [surface_shows(self.archetype, "page_error", label="error", negate=True)]

zu_patterns/rail.py

@@ -0,0 +1,86 @@
+"""Pattern → rail helpers — success/failure criteria as declarable Invariants.
+
+A pattern's predicted "done" state and its known failure modes are expressed as
+``zu_core.invariants.Invariant``s, which compile (via ``compile_spec``) to
+Monitors the loop's ZU-RAIL-5 checkpoint runs. This is FULL reuse of the §1
+machinery — no new monitor type. A breach yields ``MonitorVerdict(VIOLATION)`` →
+the existing escalation path, which is the ZU-RAIL-9 guarantee: a recognized
+pattern's prediction is VERIFIED, never trusted as ground truth.
+
+The Monitor names are namespaced ``pattern.<archetype>.<criterion>`` so audits
+read cleanly.
+"""
+
+from __future__ import annotations
+
+from zu_core import events as ev
+from zu_core.invariants import Invariant, InvariantKind, Predicate, PredicateKind
+
+
+def _name(archetype: str, criterion: str) -> str:
+    return f"pattern.{archetype}.{criterion}"
+
+
+def surface_shows(
+    archetype: str,
+    criterion: str,
+    *,
+    label: str | None = None,
+    handle: str | None = None,
+    recognized_archetype: str | None = None,
+    event_type: str = ev.SURFACE_CAPTURED,
+    negate: bool = False,
+    liveness: bool = False,
+    deadline: str | None = None,
+) -> Invariant:
+    """An Invariant over a surface event — the seam a Pattern's success/failure
+    criterion compiles to (ZU-RAIL-9).
+
+    Exactly one of ``label`` / ``handle`` / ``recognized_archetype`` is the token
+    SURFACE_CONTAINS folds the event log for. ``negate=True`` asserts ABSENCE (the
+    natural shape for "the banner is gone").
+
+    Two semantics, chosen by ``liveness``:
+
+    * ``liveness=True`` — a SUCCESS / POSTCONDITION criterion: an
+      ``EVENTUALLY``-by-deadline property. The predicted post-state is, by
+      definition, ABSENT until the interaction completes, so it must NOT be a
+      violation that early/pre-interaction surfaces lack it. The Monitor stays
+      inert until the post-state appears (then satisfied forever) OR the
+      ``deadline`` event arrives without it (then, and only then, VIOLATION).
+      ``deadline`` is the deadline event TYPE; ``None`` ⇒ any terminal event
+      (``TASK_TERMINAL``/``TASK_COMPLETED``) marking the interaction/run complete.
+      For a non-negated success token we also require the token to ACTUALLY appear
+      (``require_present``) so "no surface ever showed it" correctly violates at
+      the deadline rather than passing vacuously.
+
+    * ``liveness=False`` (default) — a SAFETY criterion: ``THROUGHOUT``. The
+      correct shape for a FAILURE CONTEXT is ``negate=True`` ("throughout: NOT
+      contains(error-context)") so the Monitor fires the instant the failure
+      context appears, and the pre-interaction state (where the context is absent)
+      satisfies it. Do NOT model a failure as a positive must-contain-THROUGHOUT —
+      that wrongly fires on every normal surface lacking the token.
+    """
+    params: dict = {"event_type": event_type, "negate": negate}
+    if recognized_archetype is not None:
+        params["archetype"] = recognized_archetype
+    elif handle is not None:
+        params["handle"] = handle
+    elif label is not None:
+        params["label"] = label
+    if liveness:
+        # A non-negated liveness token must genuinely appear by the deadline;
+        # a negated one (a state that must become ABSENT) needs no evidence floor.
+        if not negate:
+            params["require_present"] = True
+        return Invariant(
+            name=_name(archetype, criterion),
+            kind=InvariantKind.EVENTUALLY,
+            predicate=Predicate(kind=PredicateKind.SURFACE_CONTAINS, params=params),
+            applies_to=deadline,
+        )
+    return Invariant(
+        name=_name(archetype, criterion),
+        kind=InvariantKind.THROUGHOUT,
+        predicate=Predicate(kind=PredicateKind.SURFACE_CONTAINS, params=params),
+    )