@riddledc/riddle-proof 0.5.19 → 0.5.21

package/package.json

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

package/runtime/lib/recon.py

@@ -10,8 +10,8 @@ The calling agent owns the planner step between attempts by resuming the workflo
 with updated state inputs such as server_path or wait_for_selector.
 """
 
-import json, os, re, sys
-from urllib.parse import urlparse
+import json, os, re, sys, time
+from urllib.parse import parse_qsl, urlparse
 
 sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
 from util import (  # noqa: E402
@@ -44,6 +44,53 @@ if not after_dir or not os.path.exists(after_dir):
     raise SystemExit('after_worktree not found. Run setup first.')
 
 
+def record_recon_phase(phase, status='running', summary=''):
+    global s
+    ts = time.strftime('%Y-%m-%dT%H:%M:%SZ', time.gmtime())
+    try:
+        current = load_state()
+    except Exception:
+        current = dict(s)
+    runtime_step = current.get('current_runtime_step') if isinstance(current.get('current_runtime_step'), dict) else {}
+    if not runtime_step:
+        runtime_step = {
+            'step': 'recon',
+            'action': 'run',
+            'status': 'running',
+            'started_at': ts,
+            'workflow_file': 'riddle-proof-recon.lobster',
+        }
+    runtime_step['step'] = 'recon'
+    runtime_step['action'] = 'run'
+    runtime_step['status'] = 'running'
+    runtime_step['workflow_file'] = 'riddle-proof-recon.lobster'
+    runtime_step['phase'] = phase
+    runtime_step['phase_status'] = status
+    if status == 'running':
+        runtime_step['phase_started_at'] = ts
+        runtime_step.pop('phase_finished_at', None)
+    else:
+        runtime_step['phase_finished_at'] = ts
+    if summary:
+        runtime_step['summary'] = summary
+    current['current_runtime_step'] = runtime_step
+    events = current.get('runtime_events') if isinstance(current.get('runtime_events'), list) else []
+    events.append({
+        'ts': ts,
+        'kind': 'workflow.phase.' + ('started' if status == 'running' else 'finished'),
+        'step': 'recon',
+        'phase': phase,
+        'summary': summary or (phase + ' ' + status),
+        'details': {'status': status},
+    })
+    current['runtime_events'] = events[-100:]
+    current['runtime_updated_at'] = ts
+    save_state(current)
+    for key in ('current_runtime_step', 'runtime_events', 'runtime_updated_at'):
+        if key in current:
+            s[key] = current[key]
+
+
 def run(cmd, cwd, timeout=30):
     return sp.run(cmd, shell=True, cwd=cwd, capture_output=True, text=True, timeout=timeout)
 
@@ -208,7 +255,7 @@ def route_candidates(route_hints, prod_url=''):
 
     parsed_prod = urlparse((prod_url or '').strip())
     if parsed_prod.path and parsed_prod.path.strip() and parsed_prod.path != '/':
-        add(parsed_prod.path, 'prod_url path')
+        add(parsed_prod.path + (('?' + parsed_prod.query) if parsed_prod.query else ''), 'prod_url path')
 
     for hint in route_hints:
         code_fragment = hint.split(':', 2)[-1]
@@ -377,17 +424,54 @@ def has_enriched_page_state(page_state):
 
 
 def normalize_observed_path(value):
-    path = (value or '').strip()
-    if not path:
+    raw = str(value or '').strip()
+    if not raw:
         return ''
-    path = path.split('?', 1)[0].split('#', 1)[0]
+    parsed = urlparse(raw.split('#', 1)[0])
+    path = parsed.path or ''
+    query = parsed.query or ''
     if not path.startswith('/'):
-        parsed = urlparse(path)
-        path = parsed.path or path
+        path = '/' + path.lstrip('/')
     parts = path.split('/')
     if len(parts) >= 4 and parts[1] == 's':
         path = '/' + '/'.join(parts[3:])
-    return path.rstrip('/') or '/'
+    path = path.rstrip('/') or '/'
+    return path + (('?' + query) if query else '')
+
+
+def observed_location_from_page_state(page_state):
+    if not isinstance(page_state, dict):
+        return ''
+    pathname = str(page_state.get('pathname') or '').strip()
+    search = str(page_state.get('search') or '').strip()
+    if search and not search.startswith('?'):
+        search = '?' + search
+    if pathname:
+        return pathname + search
+    return str(page_state.get('href') or '').strip()
+
+
+def route_matches_expected(expected_path, observed_path):
+    expected = normalize_observed_path(expected_path)
+    observed = normalize_observed_path(observed_path)
+    if not expected or not observed:
+        return False
+    expected_parsed = urlparse(expected)
+    observed_parsed = urlparse(observed)
+    expected_pathname = expected_parsed.path.rstrip('/') or '/'
+    observed_pathname = observed_parsed.path.rstrip('/') or '/'
+    if observed_pathname != expected_pathname:
+        return False
+    expected_query = parse_qsl(expected_parsed.query, keep_blank_values=True)
+    if not expected_query:
+        return True
+    observed_query = parse_qsl(observed_parsed.query, keep_blank_values=True)
+    remaining = list(observed_query)
+    for pair in expected_query:
+        if pair not in remaining:
+            return False
+        remaining.remove(pair)
+    return True
 
 
 def build_probe_capture_script(base_script='', screenshot_label=''):
@@ -424,6 +508,8 @@ def build_probe_capture_script(base_script='', screenshot_label=''):
         '    canvasCount: document.querySelectorAll("canvas").length,',
         '    largeVisibleElements,',
         '    pathname: window.location.pathname,',
+        '    search: window.location.search,',
+        '    href: window.location.href,',
         '    title: document.title,',
         '  };',
         '});',
@@ -470,7 +556,7 @@ def evaluate_capture_quality(payload, expected_path):
 
     page_state = extract_page_state(payload)
     if isinstance(page_state, dict):
-        raw_observed_path = page_state.get('pathname', '')
+        raw_observed_path = observed_location_from_page_state(page_state)
         details.update({
             'body_text_length': page_state.get('bodyTextLength', 0),
             'interactive_elements': page_state.get('interactiveElements', 0),
@@ -520,8 +606,7 @@ def evaluate_capture_quality(payload, expected_path):
         reasons.append('page has console/runtime errors')
 
     observed_path = normalize_observed_path(details.get('observed_path'))
-    normalized_expected = (expected_path or '').rstrip('/') or '/'
-    if expected_path and observed_path and observed_path != normalized_expected:
+    if expected_path and observed_path and not route_matches_expected(expected_path, observed_path):
         raw_observed = details.get('observed_path_raw') or details.get('observed_path') or observed_path
         reasons.append(f'wrong route: expected {expected_path}, got {raw_observed}')
 
@@ -549,10 +634,14 @@ def clean_next_cache(project_dir):
 
 def build_project(project_dir, label):
     build_cmd = s.get('build_command', 'npm run build')
+    phase = label + '_build'
+    record_recon_phase(phase, 'running', 'Building ' + label + ' workspace for recon capture.')
     print('Building ' + label + ' workspace...')
     result = sp.run(build_cmd, shell=True, cwd=project_dir, capture_output=True, text=True, timeout=600)
     if result.returncode != 0:
+        record_recon_phase(phase, 'failed', label.capitalize() + ' build failed during recon.')
         raise SystemExit(label.capitalize() + ' build failed during recon: ' + result.stderr[:500])
+    record_recon_phase(phase, 'completed', label.capitalize() + ' workspace build completed for recon.')
     return {
         'stdout': result.stdout[-500:],
         'stderr': result.stderr[-500:],
@@ -589,8 +678,11 @@ def capture_workspace_baseline(project_dir, label, plan, capture_script=''):
             server_args['wait_for_selector'] = wait_for_selector
         apply_auth_context(s, server_args)
 
+        capture_phase = label + '_capture'
+        record_recon_phase(capture_phase, 'running', 'Capturing ' + label + ' recon baseline evidence.')
         shot = invoke_retry('riddle_server_preview', server_args, retries=2, timeout=420)
         append_capture_diagnostic(s, label, 'riddle_server_preview', server_args, shot)
+        record_recon_phase(capture_phase, 'completed', label.capitalize() + ' recon baseline capture completed.')
         return {
             'source': label + '_worktree',
             'mode': 'server',
@@ -606,6 +698,8 @@ def capture_workspace_baseline(project_dir, label, plan, capture_script=''):
     state_for_capture['wait_for_selector'] = wait_for_selector
     if static_reason:
         print('Recon capture (' + label + ') using static preview fallback: ' + static_reason)
+    capture_phase = label + '_capture'
+    record_recon_phase(capture_phase, 'running', 'Capturing ' + label + ' recon baseline evidence.')
     capture = capture_static_preview(state_for_capture, project_dir, label, build_probe_capture_script(capture_script, label), timeout=300, target_path=target_path)
     raw = (capture.get('raw') or {}).get('capture') or {}
     append_capture_diagnostic(
@@ -615,6 +709,7 @@ def capture_workspace_baseline(project_dir, label, plan, capture_script=''):
         {'target_path': target_path, 'static_fallback_reason': static_reason},
         raw,
     )
+    record_recon_phase(capture_phase, 'completed', label.capitalize() + ' recon baseline capture completed.')
     preview_id_key = label + '_preview_id'
     if capture.get('preview_id'):
         s[preview_id_key] = capture.get('preview_id', '')
@@ -639,12 +734,14 @@ def capture_prod_baseline(prod_url, plan, capture_script=''):
     args = {'script': script, 'timeout_sec': 60}
     apply_auth_context(s, args)
     print('Recon capture (prod) at ' + target_url)
+    record_recon_phase('prod_capture', 'running', 'Capturing production recon baseline evidence.')
     shot = invoke_retry('riddle_script', args, retries=3, timeout=180)
     append_capture_diagnostic(s, 'prod', 'riddle_script', args, shot)
+    record_recon_phase('prod_capture', 'completed', 'Production recon baseline capture completed.')
     return {
         'source': 'prod_url',
         'mode': 'remote',
-        'path': urlparse(target_url).path or (plan.get('target_path') or '/'),
+        'path': normalize_observed_path(target_url) or (plan.get('target_path') or '/'),
         'capture_url': target_url,
         'url': extract_screenshot_url(shot, 'prod'),
         'static_fallback_reason': '',

package/runtime/lib/verify.py

@@ -8,6 +8,7 @@ must assess before the wrapper routes back into author/implement/recon work or s
 """
 
 import json, os, sys, time
+from urllib.parse import parse_qsl, urlparse
 sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
 from util import (
     append_capture_diagnostic,
@@ -248,6 +249,8 @@ def build_probe_capture_script(base_script='', verification_mode='proof'):
         '    canvasCount: document.querySelectorAll("canvas").length,',
         '    largeVisibleElements,',
         '    pathname: window.location.pathname,',
+        '    search: window.location.search,',
+        '    href: window.location.href,',
         '    title: document.title,',
         '  };',
         '});',
@@ -575,16 +578,54 @@ def has_enriched_page_state(page_state):
 
 
 def normalize_observed_path(value):
-    path = (value or '').strip()
-    if not path:
+    raw = str(value or '').strip()
+    if not raw:
         return ''
-    path = path.split('?', 1)[0].split('#', 1)[0]
+    parsed = urlparse(raw.split('#', 1)[0])
+    path = parsed.path or ''
+    query = parsed.query or ''
     if not path.startswith('/'):
         path = '/' + path.lstrip('/')
     parts = path.split('/')
     if len(parts) >= 4 and parts[1] == 's':
         path = '/' + '/'.join(parts[3:])
-    return path.rstrip('/') or '/'
+    path = path.rstrip('/') or '/'
+    return path + (('?' + query) if query else '')
+
+
+def observed_location_from_page_state(page_state):
+    if not isinstance(page_state, dict):
+        return ''
+    pathname = str(page_state.get('pathname') or '').strip()
+    search = str(page_state.get('search') or '').strip()
+    if search and not search.startswith('?'):
+        search = '?' + search
+    if pathname:
+        return pathname + search
+    return str(page_state.get('href') or '').strip()
+
+
+def route_matches_expected(expected_path, observed_path):
+    expected = normalize_observed_path(expected_path)
+    observed = normalize_observed_path(observed_path)
+    if not expected or not observed:
+        return False
+    expected_parsed = urlparse(expected)
+    observed_parsed = urlparse(observed)
+    expected_pathname = expected_parsed.path.rstrip('/') or '/'
+    observed_pathname = observed_parsed.path.rstrip('/') or '/'
+    if observed_pathname != expected_pathname:
+        return False
+    expected_query = parse_qsl(expected_parsed.query, keep_blank_values=True)
+    if not expected_query:
+        return True
+    observed_query = parse_qsl(observed_parsed.query, keep_blank_values=True)
+    remaining = list(observed_query)
+    for pair in expected_query:
+        if pair not in remaining:
+            return False
+        remaining.remove(pair)
+    return True
 
 
 def collect_supporting_artifacts(payload):
@@ -767,7 +808,7 @@ def evaluate_capture_quality(payload, expected_path, verification_mode='proof'):
 
     page_state = extract_page_state(payload)
     if isinstance(page_state, dict):
-        raw_observed_path = page_state.get('pathname', '')
+        raw_observed_path = observed_location_from_page_state(page_state)
         details.update({
             'body_text_length': page_state.get('bodyTextLength', 0),
             'interactive_elements': page_state.get('interactiveElements', 0),
@@ -830,8 +871,7 @@ def evaluate_capture_quality(payload, expected_path, verification_mode='proof'):
         reasons.append('page has console/runtime errors')
 
     observed_path = normalize_observed_path(details.get('observed_path'))
-    normalized_expected = (expected_path or '').rstrip('/') or '/'
-    if isinstance(page_state, dict) and expected_path and observed_path and observed_path != normalized_expected:
+    if isinstance(page_state, dict) and expected_path and observed_path and not route_matches_expected(expected_path, observed_path):
         raw_observed = details.get('observed_path_raw') or details.get('observed_path') or observed_path
         reasons.append(f'wrong route: expected {expected_path}, got {raw_observed}')
 

package/runtime/tests/recon_verify_smoke.py

@@ -182,6 +182,27 @@ class FakeRiddle:
                     'outputs': [{'name': 'prod.png', 'url': 'https://cdn.example.com/prod.png'}],
                     'console': ['RIDDLE_PROOF_STATE:{"bodyTextLength":180,"interactiveElements":4,"pathname":"/pricing","title":"Prod"}'],
                 }
+            if 'prod.example.com/games/drum-sequencer' in script:
+                page_state = {
+                    'bodyTextLength': 240,
+                    'visibleTextSample': 'Neon Step Sequencer Monkberry Moon Delight Mix Board Play All',
+                    'interactiveElements': 8,
+                    'visibleInteractiveElements': 8,
+                    'pathname': '/games/drum-sequencer',
+                    'search': '?song=monkberry-moon-delight-tab&mix=profile',
+                    'title': 'Neon Step Sequencer',
+                    'buttons': ['Play All', 'Shuffle'],
+                    'headings': ['Neon Step Sequencer'],
+                    'links': [],
+                    'canvasCount': 1,
+                    'largeVisibleElements': [{'tag': 'canvas', 'text': ''}],
+                }
+                return {
+                    'ok': True,
+                    'screenshots': [{'url': 'https://cdn.example.com/sequencer-prod.png'}],
+                    'outputs': [{'name': 'prod.png', 'url': 'https://cdn.example.com/sequencer-prod.png'}],
+                    'console': ['RIDDLE_PROOF_STATE:' + json.dumps(page_state)],
+                }
             if 'preview.example.com' in script and '/pricing' in script:
                 return {
                     'ok': True,
@@ -189,6 +210,27 @@ class FakeRiddle:
                     'outputs': [{'name': 'before.png', 'url': 'https://cdn.example.com/before.png'}],
                     'console': ['RIDDLE_PROOF_STATE:{"bodyTextLength":180,"interactiveElements":4,"pathname":"/pricing","title":"Before"}'],
                 }
+            if 'preview.example.com' in script and '/games/drum-sequencer' in script:
+                page_state = {
+                    'bodyTextLength': 240,
+                    'visibleTextSample': 'Neon Step Sequencer Monkberry Moon Delight Mix Board Play All',
+                    'interactiveElements': 8,
+                    'visibleInteractiveElements': 8,
+                    'pathname': '/s/pv-before/games/drum-sequencer',
+                    'search': '?song=monkberry-moon-delight-tab&mix=profile',
+                    'title': 'Neon Step Sequencer',
+                    'buttons': ['Play All', 'Shuffle'],
+                    'headings': ['Neon Step Sequencer'],
+                    'links': [],
+                    'canvasCount': 1,
+                    'largeVisibleElements': [{'tag': 'canvas', 'text': ''}],
+                }
+                return {
+                    'ok': True,
+                    'screenshots': [{'url': 'https://cdn.example.com/sequencer-before.png'}],
+                    'outputs': [{'name': 'before.png', 'url': 'https://cdn.example.com/sequencer-before.png'}],
+                    'console': state_console(page_state),
+                }
             if 'preview.example.com' in script and '/games/tic-tac-toe' in script:
                 return {
                     'ok': True,
@@ -408,6 +450,35 @@ def run_verify_quality_ignores_proof_telemetry_console_text():
     assert runtime_error_quality['details']['has_errors'] is True
     assert 'console/runtime errors' in runtime_error_quality['reason']
 
+    query_payload = dict(telemetry_payload)
+    query_payload.update({
+        'visibleTextSample': 'Neon Step Sequencer Monkberry Moon Delight Mix Board Play All',
+        'pathname': '/s/pv-after/games/drum-sequencer',
+        'search': '?song=monkberry-moon-delight-tab&mix=profile&utm_source=test',
+        'title': 'Neon Step Sequencer',
+        'headings': ['Neon Step Sequencer'],
+        'buttons': ['Play All'],
+        'canvasCount': 1,
+    })
+    query_quality = namespace['evaluate_capture_quality']({
+        'ok': True,
+        'screenshots': [{'name': 'after-proof.png', 'url': 'https://cdn.example.com/after-proof.png'}],
+        'outputs': [{'name': 'after-proof.png', 'url': 'https://cdn.example.com/after-proof.png'}],
+        'console': ['RIDDLE_PROOF_STATE:' + json.dumps(query_payload)],
+    }, '/games/drum-sequencer?mix=profile&song=monkberry-moon-delight-tab', 'visual')
+    assert query_quality['valid'] is True, query_quality
+    assert query_quality['details']['observed_path'] == '/games/drum-sequencer?song=monkberry-moon-delight-tab&mix=profile&utm_source=test'
+    assert query_quality['details']['observed_path_raw'] == '/s/pv-after/games/drum-sequencer?song=monkberry-moon-delight-tab&mix=profile&utm_source=test'
+
+    missing_query_quality = namespace['evaluate_capture_quality']({
+        'ok': True,
+        'screenshots': [{'name': 'after-proof.png', 'url': 'https://cdn.example.com/after-proof.png'}],
+        'outputs': [{'name': 'after-proof.png', 'url': 'https://cdn.example.com/after-proof.png'}],
+        'console': ['RIDDLE_PROOF_STATE:' + json.dumps({**query_payload, 'search': '?song=monkberry-moon-delight-tab'})],
+    }, '/games/drum-sequencer?mix=profile&song=monkberry-moon-delight-tab', 'visual')
+    assert missing_query_quality['valid'] is False
+    assert 'wrong route' in missing_query_quality['reason']
+
     strong_delta = namespace['extract_visual_delta']({
         'ok': True,
         'result': {
@@ -659,6 +730,49 @@ def run_recon_then_author_request():
         shutil.rmtree(tempdir, ignore_errors=True)
 
 
+def run_recon_preserves_query_route():
+    tempdir = Path(tempfile.mkdtemp(prefix='riddle-proof-query-route-'))
+    state_path = tempdir / 'state.json'
+    try:
+        query_route = '/games/drum-sequencer?song=monkberry-moon-delight-tab&mix=profile'
+        state = base_state(
+            tempdir,
+            reference='both',
+            prod_url='https://prod.example.com' + query_route,
+        )
+        state.update({
+            'server_path': query_route,
+            'change_request': 'Make a tiny harmless visible sequencer helper-copy change.',
+            'success_criteria': 'The Monkberry profile sequencer route is loaded and visible.',
+        })
+        write_state(state_path, state)
+        os.environ['RIDDLE_PROOF_STATE_FILE'] = str(state_path)
+
+        fake = FakeRiddle()
+        load_util_with_fake(fake)
+        load_module('recon_query_route', RECON_PATH)
+        after_recon = json.loads(state_path.read_text())
+
+        latest_attempt = after_recon['recon_results']['attempt_history'][-1]
+        before = latest_attempt['captured_baselines']['before']
+        prod = latest_attempt['captured_baselines']['prod']
+        assert before['path'] == query_route
+        assert prod['path'] == query_route
+        assert before['observation']['valid'] is True, before['observation']
+        assert prod['observation']['valid'] is True, prod['observation']
+        assert before['observation']['details']['observed_path'] == query_route
+        assert prod['observation']['details']['observed_path'] == query_route
+        assert 'wrong route' not in before['observation']['reason']
+        assert 'wrong route' not in prod['observation']['reason']
+        return {
+            'ok': True,
+            'before_observed_path': before['observation']['details']['observed_path'],
+            'prod_observed_path': prod['observation']['details']['observed_path'],
+        }
+    finally:
+        shutil.rmtree(tempdir, ignore_errors=True)
+
+
 def run_recon_prefers_route_literals_over_import_paths():
     tempdir = Path(tempfile.mkdtemp(prefix='riddle-proof-route-literals-'))
     state_path = tempdir / 'state.json'
@@ -1369,6 +1483,7 @@ if __name__ == '__main__':
         'implement_records_detection_when_changes_missing': run_implement_records_detection_when_changes_missing(),
         'verify_quality_ignores_proof_telemetry_console_text': run_verify_quality_ignores_proof_telemetry_console_text(),
         'recon_then_author_request': run_recon_then_author_request(),
+        'recon_preserves_query_route': run_recon_preserves_query_route(),
         'recon_route_literal_preference': run_recon_prefers_route_literals_over_import_paths(),
         'recon_hint_root_preference': run_recon_prefers_hint_root_over_single_route_literal(),
         'author_applies_supervisor_packet': run_author_applies_supervisor_packet(),