@riddledc/riddle-proof 0.8.1 → 0.8.2

package/dist/types.d.cts

@@ -162,6 +162,7 @@ interface RiddleProofProofContract {
     capture_script?: string;
     artifact_contract?: Record<string, unknown>;
     assertions?: unknown;
+    interaction_contract?: Record<string, unknown>;
     baseline_understanding?: Record<string, unknown>;
     route_assumptions?: Record<string, unknown>;
     stop_condition?: string;

package/dist/types.d.ts

@@ -162,6 +162,7 @@ interface RiddleProofProofContract {
     capture_script?: string;
     artifact_contract?: Record<string, unknown>;
     assertions?: unknown;
+    interaction_contract?: Record<string, unknown>;
     baseline_understanding?: Record<string, unknown>;
     route_assumptions?: Record<string, unknown>;
     stop_condition?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@riddledc/riddle-proof",
-  "version": "0.8.1",
+  "version": "0.8.2",
   "description": "Reusable Riddle Proof contracts and helpers for evidence-backed agent changes.",
   "license": "MIT",
   "author": "RiddleDC",

package/runtime/lib/author.py

@@ -53,6 +53,10 @@ def sanitize_rationale(value):
     return out[:6]
 
 
+def optional_record(value):
+    return value if isinstance(value, dict) else {}
+
+
 def recon_baseline_understanding(state):
     assessment = state.get('recon_assessment') or {}
     understanding = assessment.get('baseline_understanding') or state.get('recon_baseline_understanding') or {}
@@ -145,12 +149,15 @@ def author_request_payload(state, reference, baselines, current_plan, hypothesis
             'capture_script': fallback_capture_script,
             'proof_plan': fallback_proof_plan,
         },
+        'interaction_contract': optional_record(state.get('interaction_contract')),
+        'proof_contract': optional_record(state.get('proof_contract')),
         'instructions': [
             'The supervising agent owns proof authoring. Use the recon-confirmed route and baselines instead of inventing a new context.',
             'Treat baseline_understanding as the required before-state review. The proof plan must name the observed before state, requested delta, and stop condition.',
             'Return the authored packet via author_packet_json when possible. You may also set proof_plan, capture_script, server_path, and wait_for_selector directly.',
             'Keep capture_script concise Playwright statements.',
             'For visual/UI proof, include saveScreenshot(\'after-proof\') exactly once.',
+            'For interaction proof, preserve the interaction contract and name the expected terminal route/state separately from the initial route.',
             'For playable/gameplay proof, start the experience, send keyboard or pointer input, sample state before/after, measure non-HUD playfield/canvas pixel deltas across time, and return a JSON-serializable evidence object with playability or playability_evidence version riddle-proof.playability.v1.',
             'For data/audio/log/metric/custom proof, screenshots are optional; collect measurements inside page.evaluate, assign the result to an evidence variable, and return that evidence object from capture_script.',
             'Do not assign globalThis.__riddleProofEvidence, window.__riddleProofEvidence, or self.__riddleProofEvidence in the worker context. Avoid global evidence assignment unless it is inside page.evaluate for compatibility with older packets.',
@@ -176,6 +183,13 @@ def author_request_payload(state, reference, baselines, current_plan, hypothesis
                 'server_path': 'string',
                 'wait_for_selector': 'string',
                 'reference': 'string',
+                'expected_terminal_path': 'string',
+            },
+            'interaction_contract': {
+                'start_path': 'string',
+                'expected_terminal_path': 'string',
+                'expected_terminal_state': 'object',
+                'actions': ['string'],
             },
             'rationale': ['string'],
             'confidence': 'high | medium | low',
@@ -215,6 +229,8 @@ provided_payload = {
     'capture_script': first_non_empty(supervisor_packet.get('capture_script'), s.get('capture_script')),
     'baseline_understanding_used': supervisor_packet.get('baseline_understanding_used') or recon_baseline_understanding(s),
     'refined_inputs': supervisor_packet.get('refined_inputs') or {},
+    'interaction_contract': optional_record(supervisor_packet.get('interaction_contract') or supervisor_packet.get('interactionContract') or s.get('interaction_contract')),
+    'proof_contract': optional_record(supervisor_packet.get('proof_contract') or supervisor_packet.get('proofContract') or s.get('proof_contract')),
     'rationale': supervisor_packet.get('rationale', s.get('supervisor_author_rationale', [])),
     'confidence': first_non_empty(supervisor_packet.get('confidence'), s.get('supervisor_author_confidence'), 'medium').lower(),
     'summary': first_non_empty(supervisor_packet.get('summary'), s.get('supervisor_author_summary')),
@@ -260,6 +276,13 @@ refined = provided_payload['refined_inputs'] if isinstance(provided_payload['ref
 refined_path = normalize_path(first_non_empty(refined.get('server_path'), s.get('server_path'), default_path)) or '/'
 refined_selector = first_non_empty(refined.get('wait_for_selector'), s.get('wait_for_selector'), default_selector)
 refined_reference = first_non_empty(refined.get('reference'), reference) or reference
+expected_terminal_path = normalize_path(first_non_empty(
+    refined.get('expected_terminal_path'),
+    refined.get('expected_after_path'),
+    supervisor_packet.get('expected_terminal_path'),
+    supervisor_packet.get('expected_after_path'),
+    s.get('expected_terminal_path'),
+))
 confidence = provided_payload['confidence'] if provided_payload['confidence'] in ('high', 'medium', 'low') else 'medium'
 rationale = sanitize_rationale(provided_payload['rationale'])
 summary = provided_payload['summary'] or 'Supervising agent supplied the proof packet from recon observations.'
@@ -272,7 +295,10 @@ authored_packet = {
         'server_path': refined_path,
         'wait_for_selector': refined_selector,
         'reference': refined_reference,
+        'expected_terminal_path': expected_terminal_path,
     },
+    'interaction_contract': provided_payload['interaction_contract'],
+    'proof_contract': provided_payload['proof_contract'],
     'rationale': rationale,
     'confidence': confidence,
     'mode': 'supervising_agent',
@@ -281,6 +307,12 @@ authored_packet = {
 }
 
 s['server_path'] = refined_path
+if expected_terminal_path:
+    s['expected_terminal_path'] = expected_terminal_path
+if authored_packet['interaction_contract']:
+    s['interaction_contract'] = authored_packet['interaction_contract']
+if authored_packet['proof_contract']:
+    s['proof_contract'] = authored_packet['proof_contract']
 if refined_selector:
     s['wait_for_selector'] = refined_selector
 elif s.get('wait_for_selector'):

package/runtime/lib/setup.py

@@ -563,6 +563,9 @@ if remote_audit_mode():
     s['author_status'] = 'ready'
     s['proof_plan_status'] = 'ready'
     s['proof_plan'] = (s.get('proof_plan') or 'Audit the current prod_url target and capture current evidence without requiring a repo diff.').strip()
+    if not (s.get('capture_script') or '').strip():
+        s['capture_script'] = 'await page.waitForTimeout(1500);'
+        s['capture_script_source'] = 'default_remote_audit_current_target'
     s['dependency_install'] = {
         'shared': 'skipped:remote_audit',
         'before': 'skipped:remote_audit',

package/runtime/lib/verify.py

@@ -55,6 +55,7 @@ VISUAL_FIRST_MODES = {
     'visual', 'render', 'interaction', 'ui', 'layout', 'screenshot',
     'canvas', 'animation',
 }
+INTERACTION_MODES = {'interaction', 'interactive', 'user_flow', 'user-flow', 'workflow'}
 PLAYABILITY_MODES = {'playable', 'gameplay', 'game'}
 PROOF_EVIDENCE_REQUIRED_MODES = {'audio'}
 MIN_VISUAL_DELTA_PERCENT = 0.5
@@ -1891,6 +1892,179 @@ def route_matches_expected(expected_path, observed_path):
     return True
 
 
+EXPLICIT_TERMINAL_PATH_KEYS = (
+    'expected_terminal_path', 'expectedTerminalPath',
+    'expected_terminal_route', 'expectedTerminalRoute',
+    'terminal_path', 'terminalPath',
+    'terminal_route', 'terminalRoute',
+    'expected_after_path', 'expectedAfterPath',
+    'expected_after_route', 'expectedAfterRoute',
+    'after_path', 'afterPath',
+    'after_route', 'afterRoute',
+    'expected_final_path', 'expectedFinalPath',
+    'expected_final_route', 'expectedFinalRoute',
+    'final_path', 'finalPath',
+    'final_route', 'finalRoute',
+)
+LOCATION_PATH_KEYS = ('path', 'pathname', 'route', 'url', 'href')
+AFTER_STATE_KEYS = (
+    'after', 'after_state', 'afterState',
+    'expected_after', 'expectedAfter',
+    'terminal', 'terminal_state', 'terminalState',
+    'expected_terminal', 'expectedTerminal',
+    'final', 'final_state', 'finalState',
+    'expected_final', 'expectedFinal',
+)
+CONTRACT_STATE_KEYS = (
+    'interaction_contract', 'interactionContract',
+    'proof_contract', 'proofContract',
+    'contract',
+    'route_assumptions', 'routeAssumptions',
+    'refined_inputs', 'refinedInputs',
+    'assertions', 'checks',
+)
+
+
+def path_candidate(value):
+    if not isinstance(value, str):
+        return ''
+    raw = value.strip()
+    if not raw:
+        return ''
+    if raw.startswith(('http://', 'https://', '/', '?')):
+        return normalize_observed_path(raw)
+    return ''
+
+
+def record_path_candidate(record, allow_location_keys=False):
+    if not isinstance(record, dict):
+        return ''
+    keys = list(EXPLICIT_TERMINAL_PATH_KEYS)
+    if allow_location_keys:
+        keys.extend(LOCATION_PATH_KEYS)
+    for key in keys:
+        candidate = path_candidate(record.get(key))
+        if candidate:
+            return candidate
+    return ''
+
+
+def terminal_path_from_record(record, depth=0):
+    if not isinstance(record, dict) or depth > 4:
+        return ''
+    candidate = record_path_candidate(record)
+    if candidate:
+        return candidate
+    for key in AFTER_STATE_KEYS:
+        value = record.get(key)
+        if isinstance(value, dict):
+            candidate = record_path_candidate(value, allow_location_keys=True) or terminal_path_from_record(value, depth + 1)
+            if candidate:
+                return candidate
+        elif isinstance(value, list):
+            for item in value:
+                candidate = terminal_path_from_record(item, depth + 1)
+                if candidate:
+                    return candidate
+    for key in CONTRACT_STATE_KEYS:
+        value = record.get(key)
+        if isinstance(value, dict):
+            candidate = terminal_path_from_record(value, depth + 1)
+            if candidate:
+                return candidate
+        elif isinstance(value, list):
+            for item in value:
+                candidate = terminal_path_from_record(item, depth + 1)
+                if candidate:
+                    return candidate
+    return ''
+
+
+def interaction_assertions_pass(value):
+    for record in proof_evidence_records(value):
+        if any(record.get(key) is False for key in (
+            'passed', 'ok', 'proofReady', 'proof_ready', 'routeMatches', 'route_matches',
+        )):
+            return False
+        if any(record.get(key) is True for key in (
+            'passed', 'ok', 'proofReady', 'proof_ready', 'interactionPassed', 'interaction_passed',
+        )):
+            return True
+        for key in ('assertions', 'checks', 'predicates', 'expectations'):
+            checks = record.get(key)
+            if isinstance(checks, dict):
+                bools = [value for value in checks.values() if isinstance(value, bool)]
+                if bools:
+                    return all(bools)
+            elif isinstance(checks, list):
+                bools = []
+                for item in checks:
+                    if isinstance(item, bool):
+                        bools.append(item)
+                    elif isinstance(item, dict):
+                        for flag_key in ('passed', 'ok', 'valid'):
+                            if isinstance(item.get(flag_key), bool):
+                                bools.append(item.get(flag_key))
+                                break
+                if bools:
+                    return all(bools)
+    return False
+
+
+def interaction_terminal_path_from_evidence(proof_evidence):
+    for record in proof_evidence_records(proof_evidence):
+        candidate = terminal_path_from_record(record)
+        if candidate:
+            return candidate, 'proof_evidence_contract'
+    if interaction_assertions_pass(proof_evidence):
+        for record in proof_evidence_records(proof_evidence):
+            for key in AFTER_STATE_KEYS:
+                value = record.get(key)
+                if isinstance(value, dict):
+                    candidate = record_path_candidate(value, allow_location_keys=True)
+                    if candidate:
+                        return candidate, 'proof_evidence_after_state'
+    return '', ''
+
+
+def interaction_terminal_path_from_state(state):
+    for key in (
+        'interaction_contract',
+        'proof_contract',
+        'supervisor_author_packet',
+        'author_packet',
+        'author_request',
+        'proof_plan_request',
+    ):
+        candidate = terminal_path_from_record(state.get(key))
+        if candidate:
+            return candidate, key
+    return '', ''
+
+
+def expected_path_for_verify(state, start_path, proof_evidence):
+    mode = normalized_verification_mode(state.get('verification_mode'))
+    normalized_start = normalize_observed_path(start_path) or '/'
+    if mode not in INTERACTION_MODES:
+        return normalized_start, {
+            'mode': mode,
+            'source': 'recon_start_path',
+            'start_path': normalized_start,
+            'expected_path': normalized_start,
+        }
+    candidate, source = interaction_terminal_path_from_state(state)
+    if not candidate:
+        candidate, source = interaction_terminal_path_from_evidence(proof_evidence)
+    expected = candidate or normalized_start
+    return expected, {
+        'mode': mode,
+        'source': source or 'recon_start_path',
+        'start_path': normalized_start,
+        'expected_path': expected,
+        'terminal_path': expected if expected != normalized_start else '',
+    }
+
+
 def collect_supporting_artifacts(payload):
     payload = enrich_capture_payload(payload)
     outputs = payload.get('outputs') or []
@@ -2063,6 +2237,7 @@ def evaluate_capture_quality(payload, expected_path, verification_mode='proof'):
     screenshot_required = screenshot_required_for_mode(mode)
     details = {
         'verification_mode': mode,
+        'expected_path': normalize_observed_path(expected_path),
         'capture_tool_error': capture_payload_error(payload),
         'has_screenshot': False,
         'screenshot_required': screenshot_required,
@@ -2138,7 +2313,12 @@ def evaluate_capture_quality(payload, expected_path, verification_mode='proof'):
     for text in iter_console_messages(console):
         if is_proof_telemetry_console_message(text):
             continue
-        if isinstance(text, str) and ('error' in text.lower() or 'failed' in text.lower()):
+        if isinstance(text, str) and (
+            'error' in text.lower()
+            or 'failed' in text.lower()
+            or 'timeout' in text.lower()
+            or 'timed out' in text.lower()
+        ):
             details['has_errors'] = True
             if len(details['capture_error_messages']) < 3:
                 details['capture_error_messages'].append(text[:500])
@@ -2231,16 +2411,41 @@ def build_capture_retry_decision(after_observation, required_baseline_present, p
     reason = after_observation.get('reason') or 'after capture is not usable yet'
     reasons.append('The after evidence is not usable yet: ' + reason)
     recommended_stage = 'recon' if 'wrong route' in reason else 'author'
+    details = after_observation.get('details') if isinstance(after_observation.get('details'), dict) else {}
+    error_messages = [
+        str(item).strip()
+        for item in (details.get('capture_error_messages') or [])
+        if str(item).strip()
+    ]
+    mismatch = None
     if recommended_stage == 'recon':
+        expected = details.get('expected_path') or ''
+        observed = details.get('observed_path_raw') or details.get('observed_path') or ''
+        if expected or observed:
+            mismatch = {
+                'field': 'route',
+                'expected_path': expected,
+                'observed_after_path': observed,
+            }
+            reasons.append('Route mismatch: expected after capture path ' + (expected or '(unknown)') + ', observed ' + (observed or '(unknown)') + '.')
+            summary = 'Verify capture route mismatch: expected ' + (expected or '(unknown)') + ', got ' + (observed or '(unknown)') + '.'
+        else:
+            summary = 'Verify capture route mismatch needs recon to refresh the reference path.'
         reasons.append('The capture appears to be on the wrong route or baseline context, so recon should refresh the reference path.')
     else:
+        if error_messages:
+            reasons.append('Capture script error: ' + error_messages[0][:500])
+            summary = 'Verify capture script failed: ' + error_messages[0][:300]
+        else:
+            summary = 'Verify needs another internal capture iteration before the evidence can be judged.'
         reasons.append('The capture plan itself needs revision, so author should tighten the proof script or framing inputs.')
     return {
         'decision': 'revise_capture',
-        'summary': 'Verify needs another internal capture iteration before the evidence can be judged.',
+        'summary': summary,
         'recommended_stage': recommended_stage,
         'continue_with_stage': recommended_stage,
         'reasons': reasons,
+        'mismatch': mismatch,
     }
 
 
@@ -2321,13 +2526,21 @@ def build_semantic_context(state, results, after_observation, expected_path):
     before_semantic = semantic_observation('before', before.get('observation') or {})
     prod_semantic = semantic_observation('prod', prod.get('observation') or {})
     after_semantic = semantic_observation('after', after_observation)
+    expected_start_path = state.get('expected_start_path') or expected_path
+    route_expectation = state.get('route_expectation') if isinstance(state.get('route_expectation'), dict) else {}
     return {
         'expected_path': expected_path,
+        'expected_start_path': expected_start_path,
+        'route_expectation': route_expectation,
         'reference': state.get('requested_reference') or state.get('reference', 'both'),
         'requested_change': state.get('change_request', ''),
         'success_criteria': (state.get('success_criteria') or '').strip(),
         'route': {
             'expected_path': expected_path,
+            'expected_after_path': expected_path,
+            'expected_start_path': expected_start_path,
+            'expected_terminal_path': route_expectation.get('terminal_path') or '',
+            'expectation_source': route_expectation.get('source') or '',
             'before_observed_path': before_semantic.get('observed_path') or before.get('path') or '',
             'prod_observed_path': prod_semantic.get('observed_path') or prod.get('path') or '',
             'after_observed_path': after_semantic.get('observed_path') or '',
@@ -2405,6 +2618,8 @@ def build_evidence_bundle(state, results, after_payload, after_observation, requ
         'verification_mode': normalized_verification_mode(state.get('verification_mode')),
         'reference': state.get('requested_reference') or state.get('reference', 'both'),
         'expected_path': expected_path,
+        'expected_start_path': state.get('expected_start_path') or expected_path,
+        'route_expectation': state.get('route_expectation') or {},
         'required_baseline_present': required_baseline_present,
         'baseline': results.get('baseline') or {},
         'semantic_context': semantic_context,
@@ -2518,6 +2733,8 @@ def build_supervisor_assessment_request(state, payload, after_observation, requi
         'status': 'needs_supervising_agent_assessment',
         'verification_mode': verification_mode,
         'expected_path': expected_path,
+        'expected_start_path': state.get('expected_start_path') or expected_path,
+        'route_expectation': state.get('route_expectation') or {},
         'required_baseline_present': required_baseline_present,
         'after_observation': after_observation,
         'supporting_artifacts': supporting,
@@ -2545,10 +2762,14 @@ def build_supervisor_assessment_request(state, payload, after_observation, requi
 
 s = load_state()
 capture_script = (s.get('capture_script') or '').strip()
-if not capture_script:
+no_implementation_mode = audit_no_diff_mode(s)
+if not capture_script and no_implementation_mode:
+    capture_script = 'await page.waitForTimeout(1500);'
+    s['capture_script'] = capture_script
+    s['capture_script_source'] = s.get('capture_script_source') or 'default_remote_audit_current_target'
+elif not capture_script:
     raise SystemExit('capture_script not set in state. Recon should finish homework first, then verify should receive the real capture plan.')
 
-no_implementation_mode = audit_no_diff_mode(s)
 if not implementation_ready_for_verify(s):
     raise SystemExit('Implementation not recorded. Make the code changes and run riddle-proof-implement before verify.')
 if no_implementation_mode and s.get('implementation_status') != 'not_required':
@@ -2568,15 +2789,17 @@ if not no_implementation_mode and (not after_dir or not os.path.exists(after_dir
 
 build_cmd = s.get('build_command', 'npm run build')
 recon_baselines = ((s.get('recon_results') or {}).get('baselines') or {})
-expected_path = (
+capture_start_path = (
     (recon_baselines.get('before') or {}).get('path')
     or (recon_baselines.get('prod') or {}).get('path')
     or ((s.get('recon_hypothesis') or {}).get('target_path'))
     or s.get('server_path')
     or '/'
 )
+expected_path = capture_start_path
+s['expected_start_path'] = normalize_observed_path(capture_start_path) or '/'
 verification_mode = normalized_verification_mode(s.get('verification_mode'))
-proof_session_seed = capture_proof_session_seed(s, expected_path)
+proof_session_seed = capture_proof_session_seed(s, s['expected_start_path'])
 probe_capture_script = build_probe_capture_script(capture_script, verification_mode, proof_session_seed, s.get('viewport_matrix'))
 results = {
     'baseline': {
@@ -2751,6 +2974,13 @@ else:
         results['after'] = {'screenshots': [{'url': capture.get('url', '')}] if capture.get('url') else [], 'raw': capture.get('raw')}
         s['after_cdn'] = capture.get('url', '')
 
+proof_evidence_for_route = extract_proof_evidence(after_payload)
+expected_path, route_expectation = expected_path_for_verify(s, s.get('expected_start_path') or capture_start_path, proof_evidence_for_route)
+s['route_expectation'] = route_expectation
+s['expected_path'] = expected_path
+if route_expectation.get('terminal_path'):
+    s['expected_terminal_path'] = route_expectation.get('terminal_path')
+
 after_viewport_matrix = capture_viewport_matrix_status(s, after_payload, 'after-proof')
 after_observation = evaluate_capture_quality(after_payload, expected_path, verification_mode)
 details = after_observation.get('details') if isinstance(after_observation.get('details'), dict) else {}
@@ -2815,7 +3045,12 @@ if existing_prod:
 summary_lines.append('After screenshot: ' + (s.get('after_cdn') or '(none)'))
 if after_viewport_matrix.get('status') not in ('not_requested', ''):
     summary_lines.append('Viewport matrix: ' + after_viewport_matrix.get('status', 'unknown') + ' (' + str(len(after_viewport_matrix.get('executed') or [])) + '/' + str(len(after_viewport_matrix.get('requested') or [])) + ' captured)')
-summary_lines.append('Expected proof path from recon: ' + expected_path)
+expected_start_path = s.get('expected_start_path') or expected_path
+if expected_start_path and expected_start_path != expected_path:
+    summary_lines.append('Expected start path from recon: ' + expected_start_path)
+    summary_lines.append('Expected terminal proof path: ' + expected_path)
+else:
+    summary_lines.append('Expected proof path from recon: ' + expected_path)
 summary_lines.append('After observation: ' + after_observation['reason'])
 supporting = results['after'].get('supporting_artifacts') or {}
 if supporting.get('has_structured_payload'):
@@ -2901,7 +3136,7 @@ has_good_evidence = (
 if has_good_evidence:
     s['capture_hint_saved'] = record_successful_capture_hint(
         s,
-        server_path=expected_path or s.get('server_path') or '/',
+        server_path=s.get('expected_start_path') or expected_path or s.get('server_path') or '/',
         wait_for_selector=s.get('wait_for_selector') or '',
         observed_path=observed_path,
         source_stage='verify',
@@ -2923,6 +3158,8 @@ if has_good_evidence:
         'status': s['verify_status'],
         'summary': 'Verify captured usable evidence and is waiting for supervising-agent proof assessment.',
         'expected_path': expected_path,
+        'expected_start_path': s.get('expected_start_path') or expected_path,
+        'route_expectation': s.get('route_expectation') or {},
         'latest_observation': after_observation,
         'next_stage_options': next_stage_options,
         'recommended_stage': None,
@@ -2949,6 +3186,8 @@ else:
         'status': s['verify_status'],
         'summary': capture_retry['summary'],
         'expected_path': expected_path,
+        'expected_start_path': s.get('expected_start_path') or expected_path,
+        'route_expectation': s.get('route_expectation') or {},
         'latest_observation': after_observation,
         'capture_quality': capture_retry,
         'next_stage_options': next_stage_options,