SR-167: Post-Action Verifier Node in LangGraph (Reliability Phase 1)

[Delqhi]

SR-167 — Phase 1: Post-Action-Verifier-Node im LangGraph

Reliability-Push Phase 1 of 5 — see meta-tracker for full picture.
Owner-Note (CEO): Höchster ROI. Schließt das Loch, durch das Conjoint heute morgen entkommen ist (selected_card = None wäre live in Produktion gelandet, weil keiner zwischen answer und submit schaut, ob der Klick tatsächlich gegriffen hat).

Problem

survey-cli/survey/daemon/survey_agent_graph.py hat heute diese Kanten:

START → navigate → parse → check_status → (captcha | answer | complete | error)
        answer → submit → END

Zwischen answer und submit gibt es keinen Verify-Knoten. Wenn:

• der Klick auf eine andere Stelle gerutscht ist (React-Re-Render-Race),
• das Radio-Button-Toggle stillschweigend gefailed ist (z. B. weil das Form per JS validiert und disabled),
• der Input-Text durch eine onInput-Handler-Sanitization überschrieben wurde,
• ein iFrame-Survey eine Overlay-Modal-Maske geblockt hat,

→ wird die Antwort als "erfolgreich" verbucht und committed. Keiner merkt's, außer dem Survey-Anbieter, der uns dann bant.

Lösung

A) Neuer LangGraph-Knoten verify_answer

Position: zwischen answer und submit.

# survey/daemon/survey_agent_graph.py (sketch)
graph.add_node("verify_answer", verify_answer_node)

graph.add_edge("answer", "verify_answer")
graph.add_conditional_edges(
    "verify_answer",
    route_after_verify,
    {
        "ok":       "submit",
        "retry":    "answer",        # weight-bounded loop, max 3
        "give_up":  "dlq",
    },
)

B) Neuer Modul survey/reliability/verifier.py

@dataclass
class VerificationResult:
    ok: bool
    reason: str
    evidence: dict           # before/after DOM hashes, AX-tree diff
    confidence: float        # 0.0–1.0

def verify_answer_applied(
    page: Page,
    question: Question,
    answer: Answer,
    snapshot_before: SnapshotV2,
    snapshot_after: SnapshotV2,
) -> VerificationResult:
    """
    Per-question-type checks:
    - radio:        aria-checked='true' on exactly one option == answer.choice_id
    - checkbox:     aria-checked set matches answer.choices
    - text/input:   target element .value == answer.text
    - slider:       aria-valuenow within ±1 of answer.value
    - rating:       aria-checked or .selected on the rated star
    - drag-drop:    DOM order of [data-rank] matches answer.ranking
    - conjoint:     answer.selected_card is not None AND that card has [data-selected]
    - hotspot:      DOM has a marker with answer.coordinates ± tolerance
    - max-diff:     two selections present matching answer.best, answer.worst
    - video/audio:  ad container has data-viewed='true' or similar
    """

C) Routing-Funktion

def route_after_verify(state: SurveyState) -> str:
    v = state["last_verification"]
    if v.ok:
        return "ok"
    if state["verify_attempts"] >= 3:
        return "give_up"
    # classify like retry_policy: only transient failures retry
    if v.reason in {"dom_unstable", "selector_drift", "timing_race"}:
        return "retry"
    return "give_up"

D) State-Erweiterung

class SurveyState(TypedDict):
    ...
    snapshot_before: Optional[SnapshotV2]      # taken in answer node
    last_verification: Optional[VerificationResult]
    verify_attempts: int                        # incremented on retry

Acceptance Criteria

• survey/reliability/verifier.py mit verify_answer_applied() für alle 10 Question-Types (6 SR-150 + 4 base: radio, checkbox, input, slider).
• LangGraph hat den Knoten verify_answer + die conditional edges + den dlq-Endknoten.
• SurveyState enthält snapshot_before, last_verification, verify_attempts.
• Bei 3 fehlgeschlagenen Verifizierungen → reliability/dlq.py::enqueue_failure() mit voller Evidence.
• Unit-Tests tests/test_verifier.py mit ≥ 20 Fällen (jeder Question-Type × ok/fail).
• Integration-Test: simulierter „stiller Klick-Fail" (Element existiert, aria-checked ändert sich nicht) → State landet auf dlq.
• test_conjoint_happy_path (heute xfail in SR-150) wird durch den Verifier gefangen statt durchgelassen — d. h. der Test wird umgewidmet zu „verifier flags missing selected_card" und auf passing gesetzt.
• Latency-Budget: Verifier ≤ 200 ms p95 pro Frage. Messen, in Observability loggen.

Out of Scope (folgt in Phase 2)

• Visual-Pixel-Diff (kommt in SR-168).
• Selector-Stability-Wait (kommt in SR-169).

Implementierungs-Reihenfolge (für den Agent, der das übernimmt)

1. Read survey/daemon/survey_agent_graph.py, survey/snapshot.py, survey/accessibility.py, survey/reliability/dlq.py, survey/reliability/retry_policy.py.
2. Write survey/reliability/verifier.py mit Per-Type-Funktionen + dispatch.
3. Write tests/test_verifier.py (testen mit FakePage aus existing fixtures).
4. Edit survey/daemon/survey_agent_graph.py: Knoten + Edges + State.
5. Edit survey/daemon/answer_engine.py (oder wo answer-Node läuft): snapshot vor Klick speichern in State.
6. Verify mit pytest survey-cli/tests/test_verifier.py survey-cli/tests/test_survey_agent_graph.py -v.
7. Ruff + line-length check (max 100).
8. PR mit Body, der Latency-Messung enthält.

Related

• Aus SR-163: Captcha solver mock/logic drift — re-enable 3 skipped tests in test_captcha_fallback.py #163 (CAPTCHA): Verifier sollte CAPTCHA-Solve auch verifizieren.
• Folge-Phasen: #SR-168, #SR-169, #SR-170, #SR-171.
• Meta-Tracker: #SR-172.

[Delqhi]

PR is up: feat/sr-167-verifier-node.

Scope delivered for Phase 1 of #172:

• survey/snapshot_v2.py — deterministic per-question DOM hash via a single JS round-trip. Additive, does not touch CompactSnapshot.
• survey/daemon/verifier.py — pure verify_action(questions, answers, snapshot_before, snapshot_after) returning VerificationResult(ok, mismatches, dom_unstable, unchanged_qids). Strategies per QuestionType: RADIO, CHECKBOX, DROPDOWN, OPEN_TEXT, SLIDER, NUMBER, with a frame-must-exist fallback.
• survey/daemon/survey_agent_graph.py — new _verify node between _answer and _submit. AgentState extended with snapshot_before, last_verification, verify_attempts. MAX_VERIFY_ATTEMPTS=2, counters reset per page in _parse. dom_unstable routes straight to handle_error — no infinite retry on flapping DOMs.
• tests/test_verifier.py (12 cases) + tests/test_snapshot_v2.py — no Playwright, synthetic controls via snapshot_v2.from_controls.
• agents.md at the repo root — central brain file. Documents the meta plan, all 5 phases, path doctrine, state shape, banned methods, test policy, and how to add a new question type. From here on out, every PR keeps it current.

Phase 2 (#168, skip-on-stable-hash) consumes VerificationResult.unchanged_qids directly. No further plumbing needed when that one lands.

[Delqhi]

Closure-Pfad (Agent One, 2026-05-13)

Status: PR #175 existiert (+1344 LoC, 4 files), aber während Wave-1 (SR-194 fixes) gewartet. Empfohlene Reihenfolge zur Schließung:

Vor Merge von PR #175

Mindestens diese SR-194 Fixes müssen rein, weil der Verifier-Node sonst gegen kaputten Code testet:

1. PR fix(daemon): SR-194 A2-A5 — repair daemon CLI startup (run_forever + constructor drift) #211 (A2-A5 daemon CLI repair) — der LangGraph-Bootstrap muss überhaupt durchlaufen, sonst kann kein Verifier-Knoten registriert werden.
2. PR fix(tools): SR-194 A6 — add CommandRegistry.record_command for tool telemetry #213 (A6 CommandRegistry.record_command) — der Verifier soll genau diese Methode benutzen, um seine Verify-Calls zu loggen.
3. PR fix(cdp): SR-194 B1 — guard WebSocket | None call sites #214 (B1 WebSocket None-checks) — CDP-Calls aus dem Verifier müssen den Reconnect-Pfad nutzen können, ohne AttributeError.

Danach: PR #175 mergen, dann SR-168 (#168) PR vorbereiten, der die Triple-Channel-Attestation in den hier eingeführten Verifier-Knoten steckt.

State-of-the-art-Hinweise (best practices, die jetzt rein sollten, nicht nachträglich)

• Idempotenter Retry-Loop: Verifier muss bei Mismatch nicht direkt fail'en, sondern N=2 Re-Verifications mit kurzem wait_for_network_idle dazwischen (SR-174 / PR feat(reliability+network): SR-174 — network-state pre-click gate (#179) #185 wartet auf merge — wenn das vor feat(graph): SR-167 post-action verifier node + agents.md brain file #175 reinkommt, hier sofort einbinden).
• DOM-AX-Vision-Channel-Slot bereits offen lassen: Verifier-Output sollte ein dict mit {"dom_evidence": ..., "ax_evidence": ..., "vision_evidence": ...} zurückgeben, auch wenn aktuell nur DOM gefüllt ist. Damit SR-168 ohne Schema-Change einsteigen kann.
• structlog-Event statt print/logger.info: jeder Verify-Schritt loggt mit event="answer_verified", survey_id, question_hash, attempt_n, mismatch_reason. Vorgriff auf SR-191 (SR-191: Migrate to structlog — Phase 1 #190).
• Prometheus-Counter an der Stelle vorbereiten, auch wenn prometheus_client noch nicht registriert ist: VERIFY_ATTEMPTS, VERIFY_MISMATCHES, VERIFY_LATENCY_MS. Vorgriff auf SR-161.
• Hash-stabile Question-IDs: der Knoten muss die Question by stable hash referenzieren (nicht durch DOM-Selector, der instabil ist) — sonst false positives bei React-Re-Renders.

Akzeptanz (verbindlich)

• Ein Verifier-Knoten zwischen answer und submit im SurveyAgentGraph.
• Bei Mismatch: maximal 2 Retries mit Network-Idle dazwischen, dann END mit survey_id + DLQ-Entry.
• Strukturierter Output mit Slots für DOM/AX/Vision (auch wenn nur DOM gefüllt).
• Mindestens 3 Integrationstests in survey-cli/tests/test_verifier_node.py: happy-path, single-retry-then-success, double-retry-then-dlq.
• mypy Phase 1 informational — keine neuen attr-defined/union-attr durch den neuen Node (post-PR-ci(mypy): SR-190 — enforce type-checking (informational phase) (#189) #193).

Was NICHT in diesen PR gehört

• Triple-Channel-Attestation (das ist SR-168 / SR-168: Triple-Channel Attestation (DOM+AX+Vision) (Reliability Phase 2) #168).
• Vision-Planner (das ist SR-175 / SR-175: Multimodal Vision+AX Planner + Bezier Click Motion #180).
• Selector-Stability-Index (das ist SR-169 / SR-169: Selector Stability + DOM-Freeze Gate (Reliability Phase 3) #169).

Sobald die o.g. Pre-Merges durch sind: PR #175 wird per Merges-API rebased (analog zu #185/#191/#192 heute), CI-Status bestätigt, dann merged.

Ref #172 (META), #196 (Merge-Plan), #194 (SR-190 findings).