opguard-harness 0.1.0__py3-none-any.whl

opguard_harness/__init__.py

@@ -0,0 +1,3 @@
+"""OpGuard orchestration, independent of the tracing runtime and model provider."""
+
+__version__ = '0.1.0'

opguard_harness/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

opguard_harness/cli.py

@@ -0,0 +1,35 @@
+import argparse
+import json
+import sys
+
+from .tools import TOOLS, dispatch
+
+
+def main():
+    parser = argparse.ArgumentParser(description='Provider-neutral OpGuard agent tools')
+    parser.add_argument('--root', default='./experiments', help='Persistent experiment store; shared with workers')
+    sub = parser.add_subparsers(dest='command', required=True)
+    sub.add_parser('tools', help='Print function schemas')
+    call = sub.add_parser('call', help='Execute one tool and print one JSON response')
+    call.add_argument('name', choices=[t['name'] for t in TOOLS])
+    call.add_argument('--arguments', help='JSON file; defaults to stdin')
+    args = parser.parse_args()
+    if args.command == 'tools':
+        print(json.dumps({'protocol_version': 1, 'tools': TOOLS}, indent=2))
+        return 0
+    try:
+        if args.arguments:
+            with open(args.arguments) as stream:
+                arguments = json.load(stream)
+        else:
+            arguments = json.load(sys.stdin)
+        result = dispatch(args.root, args.name, arguments)
+        print(json.dumps({'ok': True, 'result': result}, ensure_ascii=False))
+        return 0
+    except Exception as exc:
+        print(json.dumps({'ok': False, 'error': {'type': type(exc).__name__, 'message': str(exc)}}))
+        return 1
+
+
+if __name__ == '__main__':
+    sys.exit(main())

opguard_harness/engine.py

@@ -0,0 +1,181 @@
+"""A fixed, inspectable workflow. The agent chooses when to advance or refine."""
+from datetime import datetime, timezone
+import json
+import os
+from pathlib import Path
+import subprocess
+import uuid
+
+from .spec import validate
+from .store import Store, atomic_json
+
+STAGES = [(side, phase) for side in ('baseline', 'candidate')
+          for phase in ('discover', 'prepare', 'trace')] + [('comparison', 'compare')]
+
+
+def now():
+    return datetime.now(timezone.utc).isoformat()
+
+
+class Harness:
+    def __init__(self, root):
+        self.store = Store(root)
+
+    def create(self, spec):
+        spec = validate(spec)
+        experiment_id = uuid.uuid4().hex
+        self.store.path(experiment_id).mkdir()
+        record = {'version': 1, 'id': experiment_id, 'created_at': now(), 'status': 'pending',
+                  'spec': spec, 'stages': [{'side': side, 'action': action, 'status': 'pending',
+                                         'attempts': []} for side, action in STAGES]}
+        self.store.save(record)
+        return self.status(experiment_id)
+
+    def status(self, experiment_id):
+        record = self.store.load(experiment_id)
+        stage = next((s for s in record['stages'] if s['status'] != 'succeeded'), None)
+        return {'id': experiment_id, 'status': record['status'], 'next':
+                {'side': stage['side'], 'action': stage['action']} if stage else None,
+                'stages': record['stages']}
+
+    def results(self, experiment_id):
+        record = self.store.load(experiment_id)
+        last = record['stages'][-1]
+        return {'id': experiment_id, 'status': record['status'],
+                'comparison': last.get('result'), 'verdict': 'not_evaluated',
+                'complete': record['status'] == 'succeeded'}
+
+    def refine(self, experiment_id, spec):
+        # Explicit full spec, fresh experiment; old evidence stays immutable.
+        self.store.load(experiment_id)
+        child = self.create(spec)
+        with self.store.locked(child['id']) as record:
+            record['parent'] = experiment_id
+            self.store.save(record)
+        return child
+
+    def advance(self, experiment_id):
+        with self.store.locked(experiment_id) as record:
+            stage = next((s for s in record['stages'] if s['status'] != 'succeeded'), None)
+            if stage is None:
+                return self.status(experiment_id)
+            if stage['status'] == 'running':
+                raise RuntimeError('Previous controller interrupted. Inspect the recorded process/logs and use recover; do not launch duplicate workers')
+            if len(stage['attempts']) >= record['spec']['max_stage_attempts']:
+                raise RuntimeError('Stage attempt budget exhausted; refine into a new experiment')
+            number = len(stage['attempts']) + 1
+            attempt_dir = self.store.path(experiment_id) / f'{stage["side"]}-{stage["action"]}-{number}'
+            attempt_dir.mkdir()
+            request = self._request(record, stage, attempt_dir)
+            atomic_json(attempt_dir / 'request.json', request)
+            attempt = {'started_at': now(), 'directory': str(attempt_dir), 'status': 'running'}
+            stage['attempts'].append(attempt)
+            stage['status'] = record['status'] = 'running'
+            self.store.save(record)
+            env = {k: v for k, v in os.environ.items() if not k.startswith('OPGUARD_')}
+            env['OPGUARD_AUTOSTART'] = '0'
+            command = [*record['spec']['backend'], stage['action'], '--request', str(attempt_dir / 'request.json')]
+            try:
+                with (attempt_dir / 'response.json').open('w') as out, (attempt_dir / 'backend.log').open('w') as err:
+                    # Inherit signals: Ctrl-C reaches the backend, which unwinds its
+                    # source transaction. Never automatically retry interrupted jobs.
+                    process = subprocess.Popen(command, stdout=out, stderr=err, env=env)
+                    attempt['pid'] = process.pid
+                    self.store.save(record)
+                    code = process.wait()
+                response = json.loads((attempt_dir / 'response.json').read_text())
+                if code or response.get('protocol_version') != 1 or response.get('ok') is not True:
+                    raise RuntimeError(f'Backend failed: {response.get("error", response)}')
+                result = response['result']
+                self._validate_result(stage['action'], request, result)
+                stage['result'] = result
+                stage['status'] = attempt['status'] = 'succeeded'
+                record['status'] = 'succeeded' if all(s['status'] == 'succeeded' for s in record['stages']) else 'pending'
+            except Exception as exc:
+                stage['status'] = attempt['status'] = 'failed'
+                record['status'] = 'failed'
+                attempt['error'] = str(exc)
+            finally:
+                attempt['finished_at'] = now()
+                self.store.save(record)
+            return self.status(experiment_id)
+
+    def recover(self, experiment_id):
+        # A controller crash is ambiguous. Only acknowledge after backend exit and
+        # completed source restoration; no stale PID guessing or automatic overwrite.
+        with self.store.locked(experiment_id) as record:
+            stage = next((s for s in record['stages'] if s['status'] == 'running'), None)
+            if stage is None:
+                raise ValueError('No interrupted running stage')
+            attempt = stage['attempts'][-1]
+            pid = attempt.get('pid')
+            if pid:
+                try:
+                    os.kill(pid, 0)
+                except ProcessLookupError:
+                    pass
+                else:
+                    raise RuntimeError('Recorded backend PID still exists; inspect it before recovery')
+            path = Path(attempt['directory'])
+            if stage['action'] == 'trace':
+                state = path / 'output-instrument'
+                if state.exists() and not (state / 'restored.json').exists():
+                    raise RuntimeError(f'Source restoration not confirmed. Inspect originals.json in {state}; recover sources before retrying')
+            # Discovery could leave detached remote workers. A successful backend
+            # response proves its blocking launcher returned and receipts validated.
+            response_path = path / 'response.json'
+            try:
+                response = json.loads(response_path.read_text())
+            except (OSError, ValueError):
+                raise RuntimeError('No terminal backend response; verify/cancel launcher workers before creating a new experiment')
+            if response.get('protocol_version') != 1 or not isinstance(response.get('ok'), bool):
+                raise RuntimeError('Invalid terminal backend response')
+            if response['ok']:
+                request = json.loads((path / 'request.json').read_text())
+                self._validate_result(stage['action'], request, response['result'])
+                stage['result'] = response['result']
+                stage['status'] = attempt['status'] = 'succeeded'
+                record['status'] = 'succeeded' if all(s['status'] == 'succeeded' for s in record['stages']) else 'pending'
+            else:
+                stage['status'] = attempt['status'] = 'failed'
+                attempt['error'] = str(response.get('error'))
+                record['status'] = 'failed'
+            attempt['recovered_at'] = now()
+            self.store.save(record)
+        return self.status(experiment_id)
+
+    @staticmethod
+    def _result(record, side, action):
+        return next(s['result'] for s in record['stages'] if s['side'] == side and s['action'] == action)
+
+    def _request(self, record, stage, directory):
+        spec, side, action = record['spec'], stage['side'], stage['action']
+        request = {'protocol_version': 1, 'output': str(directory / 'output'),
+                   'local_root': spec['local_root'], 'timeout_seconds': spec['timeout_seconds']}
+        if side in ('baseline', 'candidate'):
+            request['workload'] = spec[side]
+        if action == 'prepare':
+            request['discovery'] = self._result(record, side, 'discover')
+        if action == 'trace':
+            request['plan'] = self._result(record, side, 'prepare')
+        if action == 'compare':
+            request.update(baseline=self._result(record, 'baseline', 'trace'),
+                           candidate=self._result(record, 'candidate', 'trace'),
+                           ranks=spec['baseline']['ranks'])
+        return request
+
+    @staticmethod
+    def _validate_result(action, request, result):
+        if not isinstance(result, dict):
+            raise ValueError('Backend result must be an object')
+        if action in ('discover', 'trace'):
+            if result.get('output') != request['output'] or result.get('ranks') != request['workload']['ranks'] or result.get('phase') != action:
+                raise ValueError('Capture result does not match the requested phase/output/ranks')
+        elif action == 'prepare':
+            if not result.get('sources') or not Path(result['config']).is_file() or not result.get('config_sha256'):
+                raise ValueError('Invalid instrumentation plan')
+        else:
+            if result.get('verdict') != 'not_evaluated' or result.get('ranks') != request['ranks'] or not result.get('reports'):
+                raise ValueError('Invalid comparison result')
+            if len(result['reports']) != len(request['ranks']) or any(not Path(p).is_file() for p in result['reports']):
+                raise ValueError('Missing comparison reports')

opguard_harness/fingerprints.py

@@ -0,0 +1,63 @@
+"""Interpret recorded regional fingerprints, without inferring value equality."""
+
+
+def _layout(tensor):
+    layout = tensor.get('xor_sig_layout')
+    values = tensor.get('xor_signature')
+    if tensor.get('xor_sig_mode') != 'bytes' or not isinstance(layout, dict):
+        return None
+    count, size = layout.get('regions'), layout.get('logical_nbytes')
+    if (layout.get('scheme') != 'flat-u32-le-v1' or type(count) is not int
+            or not 1 <= count <= 64 or type(size) is not int or size < 0):
+        return None
+    if count == 1 and type(values) in (int, float):
+        values = [values]
+    if not isinstance(values, list) or len(values) != count or any(
+            type(x) not in (int, float) or not 0 <= x <= 0xffffffff or int(x) != x for x in values):
+        return None
+    base, rem = divmod((size + 3) // 4, count)
+    ranges, start = [], 0
+    for i in range(count):
+        end = start + base + (i < rem)
+        ranges.append([min(start * 4, size), min(end * 4, size)])
+        start = end
+    if layout.get('byte_ranges') != ranges:
+        return None
+    return layout, list(map(int, values))
+
+
+def compare_regions(left, right):
+    a, b = _layout(left), _layout(right)
+    if a is None or b is None:
+        return {'status': 'unavailable', 'reason': 'missing_or_unsupported_content_fingerprint_layout'}
+    if a[0] != b[0] or left.get('dtype') != right.get('dtype'):
+        return {'status': 'incompatible', 'reason': 'different_fingerprint_layout_or_dtype'}
+    regions = [{'region': i, 'byte_range': bounds, 'left': av, 'right': bv,
+                'fingerprint_xor': av ^ bv, 'fingerprints_agree': av == bv}
+               for i, (bounds, av, bv) in enumerate(zip(a[0]['byte_ranges'], a[1], b[1]))]
+    return {'status': 'available', 'scheme': a[0]['scheme'], 'regions': regions,
+            'differing_regions': [r['region'] for r in regions if not r['fingerprints_agree']],
+            'tensor_equality': 'not_established', 'different_element_count': 'not_available',
+            'padding_assessment': 'not_determined'}
+
+
+def regional_comparisons(left, right):
+    """Same-slot proposals, or the explicit selected slots of a reviewed pair."""
+    a, b = left.get('io') or {}, right.get('io') or {}
+    claim = left.get('correspondence') or {}
+    selected = (claim.get('basis') == 'explicit_alignment_map'
+                and claim.get('peer_record_id') == right.get('record_id')
+                and claim.get('tensor_slot') is not None)
+    if selected:
+        slots = [(claim['tensor_slot'], claim['peer_tensor_slot'])]
+    else:
+        slots = [([side, i], [side, i]) for side in ('inputs', 'outputs')
+                 for i in range(min(len(a.get(side, [])), len(b.get(side, []))))]
+    tensors = []
+    for x, y in slots[:64]:
+        av, bv = a[x[0]][x[1]], b[y[0]][y[1]]
+        tensors.append({'left_tensor': x, 'right_tensor': y, **compare_regions(av, bv)})
+    return {'selection_basis': 'reviewed_tensor_slots' if selected else 'same_io_slot_candidates',
+            'tensors': tensors, 'truncated': len(slots) > 64,
+            'note': 'Region differences localize recorded byte changes, not element counts or padding noise. '
+                    'Matching regions may still contain XOR collisions. Validate semantic correspondence first.'}

opguard_harness/input_bundle.py

@@ -0,0 +1,91 @@
+"""Copy an explicit input allowlist without repository history or answer files.
+
+This is an artifact boundary, not a filesystem sandbox or a semantic leak detector.
+The caller must review the selected source and provide a separate solver workspace.
+"""
+import hashlib
+import json
+from pathlib import Path, PurePosixPath
+import shutil
+import sys
+
+
+EXCLUDED_PARTS = {".git", ".hg", ".svn", "__pycache__", "answers", "evidence"}
+
+
+def disallowed_symlink(path):
+    if not path.is_symlink():
+        return False
+    # Only exempt macOS root aliases with their exact system targets.
+    # User-created directory and file links must still be rejected.
+    return not (sys.platform == "darwin" and path in {Path("/var"), Path("/tmp")}
+                and path.resolve() == Path("/private") / path.name)
+
+
+def relative_path(value):
+    path = PurePosixPath(value)
+    if (not value or path.is_absolute() or "\\" in value
+            or any(part in {".", ".."} | EXCLUDED_PARTS for part in value.split("/"))
+            or str(path) != value or path.suffix in {".pyc", ".pyo"}):
+        raise ValueError(f"Not an input path: {value}")
+    return Path(*path.parts)
+
+
+def sha256(path):
+    digest = hashlib.sha256()
+    with path.open("rb") as stream:
+        for chunk in iter(lambda: stream.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def export_inputs(destination, files):
+    """Export {relative destination: explicit source file}; never walk a checkout.
+
+    The public manifest contains only destination paths and content hashes. Source
+    paths and case-to-answer mappings belong in the caller's private provenance.
+    """
+    destination = Path(destination)
+    prepared = []
+    for name, source in files.items():
+        target = relative_path(name)
+        if name == "manifest.json":
+            raise ValueError("manifest.json is reserved for the input inventory")
+        source = Path(source).absolute()
+        if any(disallowed_symlink(p) for p in (source, *source.parents)) or not source.is_file():
+            raise ValueError(f"Input must be a regular file without symlinks: {source}")
+        if any(part in EXCLUDED_PARTS for part in source.parts):
+            raise ValueError(f"Excluded source path: {source}")
+        prepared.append((target, source))
+    # Refuse merges into old bundles: stale captures may contain embedded answers.
+    destination.mkdir(parents=True, exist_ok=False)
+    hashes = {}
+    for target, source in prepared:
+        output = destination / target
+        output.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copyfile(source, output)
+        hashes[target.as_posix()] = sha256(output)
+    manifest = {"version": 1, "files": hashes}
+    (destination / "manifest.json").write_text(json.dumps(manifest, indent=2) + "\n")
+    return manifest
+
+
+def verify_inputs(directory):
+    """Reject missing/changed/unlisted files and symlinks before solver delivery."""
+    directory = Path(directory)
+    manifest = json.loads((directory / "manifest.json").read_text())
+    if manifest.get("version") != 1:
+        raise ValueError("Unsupported input manifest version")
+    expected = set(manifest["files"]) | {"manifest.json"}
+    actual = set()
+    for path in directory.rglob("*"):
+        if path.is_symlink():
+            raise ValueError(f"Symlink in input bundle: {path}")
+        if path.is_file():
+            actual.add(path.relative_to(directory).as_posix())
+    if actual != expected:
+        raise ValueError(f"Input inventory differs: {sorted(actual ^ expected)}")
+    for name, digest in manifest["files"].items():
+        if sha256(directory / relative_path(name)) != digest:
+            raise ValueError(f"Changed input: {name}")
+    return manifest

opguard_harness/reviews.py

@@ -0,0 +1,209 @@
+"""Artifact-scoped agent reviews and a resumable difference queue.
+
+Reviews are assertions with provenance, never automatic root-cause verdicts.
+The append-only review history is also an OpGuard alignment-map v1 document.
+"""
+import collections
+from datetime import datetime, timezone
+import fcntl
+import hashlib
+import json
+import os
+from pathlib import Path
+import subprocess
+import uuid
+
+from .spec import strings
+from .store import atomic_json
+from .trace_reader import Trace
+
+DECISIONS = {"comparable", "not_comparable", "undetermined"}
+BASES = {"observed", "source_inference", "intervention_tested", "externally_reported"}
+MAX_REVIEW_BYTES = 8 * 1024 * 1024
+
+
+def _key(left, right):
+    return tuple(sorted((left, right)))
+
+
+def _slot(trace, index, slot):
+    if (not isinstance(slot, list) or len(slot) != 2 or slot[0] not in ("inputs", "outputs")
+            or type(slot[1]) is not int or slot[1] < 0):
+        raise ValueError('Tensor slot must be [inputs|outputs, nonnegative index] in exported io')
+    values = (trace.events[index]['args'].get('io') or {}).get(slot[0], [])
+    if slot[1] >= len(values) or not isinstance(values[slot[1]], dict):
+        raise ValueError('Tensor slot is absent from exported io')
+
+
+def _validate(trace, review):
+    required = {'left_ref', 'right_ref', 'left_tensor', 'right_tensor', 'decision', 'reason', 'evidence'}
+    if (not isinstance(review, dict) or not required <= review.keys()
+            or review.keys() - required - {'id', 'created_at'}):
+        raise ValueError('Invalid review fields')
+    a, b = trace.index(review['left_ref']), trace.index(review['right_ref'])
+    left, right = trace.events[a]['args'], trace.events[b]['args']
+    if not left.get('run') or not right.get('run') or left['run'] == right['run']:
+        raise ValueError('A review must relate different runs')
+    if review['decision'] not in DECISIONS or not isinstance(review['reason'], str) or not review['reason'].strip():
+        raise ValueError('A review requires a decision and a reason')
+    evidence = review['evidence']
+    if not isinstance(evidence, list) or not evidence:
+        raise ValueError('A review requires evidence references')
+    for item in evidence:
+        if (not isinstance(item, dict) or set(item) != {'basis', 'reference'}
+                or item['basis'] not in BASES or not isinstance(item['reference'], str)
+                or not item['reference'].strip()):
+            raise ValueError('Invalid evidence basis/reference')
+    lp, rp = review['left_tensor'], review['right_tensor']
+    if (lp is None) != (rp is None):
+        raise ValueError('Select both tensor slots or neither')
+    if lp is not None:
+        if review['decision'] != 'comparable':
+            raise ValueError('Negative/undetermined reviews address the whole proposed relation; use null slots')
+        _slot(trace, a, lp)
+        _slot(trace, b, rp)
+    elif review['decision'] == 'comparable':
+        aligned = trace.aligned(a)
+        if not aligned['unique'] or aligned['peers'][0]['event_ref'] != trace.ref(b):
+            raise ValueError('New correspondences require explicit tensor slots')
+
+
+def _latest(trace, history):
+    latest = {}
+    for review in history:
+        _validate(trace, review)
+        latest[_key(review['left_ref'], review['right_ref'])] = review
+    used = set()
+    for review in latest.values():
+        if review['decision'] == 'comparable':
+            refs = {review['left_ref'], review['right_ref']}
+            if used & refs:
+                raise ValueError('Conflicting comparable reviews: one relation per operation per view')
+            used.update(refs)
+    return latest
+
+
+def _path(root, trace):
+    return Path(root).expanduser().resolve() / 'reviews' / (trace.sha + '.json')
+
+
+def _load(root, trace):
+    path = _path(root, trace)
+    if not path.exists():
+        return {'version': 1, 'artifact_sha256': trace.sha, 'reviews': []}
+    with path.open('rb') as stream:
+        raw = stream.read(MAX_REVIEW_BYTES + 1)
+    if len(raw) > MAX_REVIEW_BYTES:
+        raise ValueError('Review history exceeds the 8 MiB limit')
+    record = json.loads(raw)
+    if (record.get('version') != 1 or record.get('artifact_sha256') != trace.sha
+            or not isinstance(record.get('reviews'), list)):
+        raise ValueError('Review history belongs to another artifact or version')
+    _latest(trace, record['reviews'])
+    return record
+
+
+def review_pair(root, artifact, review):
+    trace = Trace(artifact)
+    _validate(trace, review)
+    path = _path(root, trace)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.with_suffix('.lock').open('a') as lock:
+        fcntl.flock(lock, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        record = _load(root, trace)
+        entry = {**review, 'id': uuid.uuid4().hex, 'created_at': datetime.now(timezone.utc).isoformat()}
+        record['reviews'].append(entry)
+        latest = _latest(trace, record['reviews'])
+        if len(json.dumps(record, indent=2, ensure_ascii=False).encode()) > MAX_REVIEW_BYTES:
+            raise ValueError('Review history exceeds the 8 MiB limit')
+        atomic_json(path, record)
+    return {'artifact': trace.identity(), 'review': entry, 'alignment_map': str(path),
+            'active_review_count': len(latest), 'history_count': len(record['reviews']),
+            'validation': 'agent_assertion_not_independently_verified', 'verdict': 'not_evaluated'}
+
+
+def difference_candidates(root, artifact, cursor, limit, include_reviewed):
+    if type(cursor) is not int or cursor < 0 or type(limit) is not int or not 1 <= limit <= 50:
+        raise ValueError('cursor must be nonnegative and limit between 1 and 50')
+    if type(include_reviewed) is not bool:
+        raise ValueError('include_reviewed must be boolean')
+    trace = Trace(artifact)
+    latest = _latest(trace, _load(root, trace)['reviews'])
+    candidates, seen = [], set()
+    for i in sorted(trace.ops, key=lambda i: (str(trace.events[i]['args'].get('run')),
+                                             trace.events[i]['args'].get('rank', -1),
+                                             trace.events[i].get('ts', 0), i)):
+        if trace.events[i]['args']['status'] != 'diff':
+            continue
+        alignment = trace.aligned(i)
+        peer = alignment['peers'][0] if alignment['unique'] else None
+        if peer is None:
+            # Show a declared, uniquely addressable peer even when its automatic
+            # constraints fail, so the agent can reject that proposal. The
+            # alignment consistency failure remains visible alongside it.
+            claim = trace.events[i]['args'].get('correspondence') or {}
+            proposed = trace.records.get(claim.get('peer_record_id'), [])
+            if len(proposed) == 1 and trace.events[proposed[0]]['args'].get('run') != trace.events[i]['args'].get('run'):
+                peer = trace.compact(proposed[0])
+        key = _key(trace.ref(i), peer['event_ref']) if peer else (trace.ref(i),)
+        if key in seen:
+            continue
+        seen.add(key)
+        candidates.append({'left': trace.compact(i), 'right': peer, 'alignment': alignment,
+                           'diff': trace.events[i]['args'].get('diff'), 'review': latest.get(key)})
+    if cursor > len(candidates):
+        raise ValueError('cursor is beyond this artifact candidate queue')
+    selected, position = [], cursor
+    while position < len(candidates) and len(selected) < limit:
+        item = candidates[position]
+        position += 1
+        if include_reviewed or item['review'] is None:
+            selected.append(item)
+    return {'artifact': trace.identity(), 'candidates': selected,
+            'next_cursor': position if position < len(candidates) else None,
+            'candidate_count': len(candidates),
+            'unreviewed_count': sum(item['review'] is None for item in candidates),
+            'review_counts': dict(collections.Counter(r['decision'] for r in latest.values())),
+            'alignment_map': str(_path(root, trace)) if latest else None,
+            'scope': 'grouped_by_run_rank_export_order_not_global_causality',
+            'verdict': 'not_evaluated',
+            'note': 'Reviews do not erase observations. Use include_reviewed to revisit them; undetermined is unresolved. New declared pairs appear after render_alignment.'}
+
+
+def render_alignment(root, artifact, output, backend):
+    """Freeze the current map and invoke the existing backend protocol, no workload."""
+    strings(backend, 'backend', True)
+    trace = Trace(artifact)
+    mapping = _load(root, trace)
+    if not mapping['reviews']:
+        raise ValueError('No reviews for this artifact')
+    target = Path(output).expanduser()
+    if not target.is_absolute() or target.exists():
+        raise ValueError('output must be a fresh absolute trace path')
+    directory = Path(root).expanduser().resolve() / 'review-renders' / uuid.uuid4().hex
+    directory.mkdir(parents=True)
+    map_path = directory / 'alignment-map.json'
+    atomic_json(map_path, mapping)
+    request = {'protocol_version': 1, 'artifact': str(trace.path),
+               'alignment_map': str(map_path), 'output': str(target)}
+    atomic_json(directory / 'request.json', request)
+    env = {k: v for k, v in os.environ.items() if not k.startswith('OPGUARD_')}
+    env['OPGUARD_AUTOSTART'] = '0'
+    with (directory / 'response.json').open('w') as out, (directory / 'backend.log').open('w') as err:
+        process = subprocess.run([*backend, 'align', '--request', str(directory / 'request.json')],
+                                 stdout=out, stderr=err, env=env, timeout=120)
+    response = json.loads((directory / 'response.json').read_text())
+    if process.returncode or response.get('protocol_version') != 1 or response.get('ok') is not True:
+        raise RuntimeError(f'Alignment backend failed; inspect {directory}: {response.get("error")}')
+    result = response['result']
+    rendered = Trace(target)
+    if (Path(result['artifact']).resolve() != target.resolve() or result.get('sha256') != rendered.sha
+            or result.get('source_sha256') != trace.sha
+            or result.get('map_sha256') != hashlib.sha256(map_path.read_bytes()).hexdigest()
+            or result.get('verdict') != 'not_evaluated'):
+        raise RuntimeError(f'Alignment backend returned inconsistent provenance; inspect {directory}')
+    return {**result, 'render_directory': str(directory),
+            'note': 'This is a new artifact revision. Obtain new event_refs; original trace and review history are preserved.'}
+
+
+REVIEW_TOOLS = {fn.__name__: fn for fn in (review_pair, difference_candidates, render_alignment)}

opguard_harness/spec.py

@@ -0,0 +1,69 @@
+"""An explicit launch contract. No command guessing or shell interpolation."""
+import copy
+import math
+from pathlib import Path
+
+RESERVED_ENV = {
+    'OPGUARD_AUTOSTART', 'OPGUARD_CALLSITE_TRACER', 'OPGUARD_TRACE_OUTPUT_BASE',
+    'OPGUARD_LOCAL_DUMP_TARGET', 'OPGUARD_LOCAL_DUMP_ENABLED', 'OPGUARD_LOCAL_DUMP_BASE',
+    'OPGUARD_CALLSITE_OUTPUT_DIR', 'OPGUARD_EXEC_OUTPUT_DIR', 'OPGUARD_CONFIG_PATH',
+    'OPGUARD_CALLSITE_CONFIG', 'OPGUARD_RUN_ID', 'OPGUARD_RUN_TOKEN', 'OPGUARD_TRACE_ROOT',
+    'DEFAULT_CODE_REPO_BASE',
+}
+
+
+def strings(value, name, nonempty=False):
+    if not isinstance(value, list) or (nonempty and not value) or any(
+            not isinstance(item, str) or '\0' in item for item in value):
+        raise ValueError(f'{name} must be an argv list of strings')
+    return value
+
+
+def validate(spec):
+    spec = copy.deepcopy(spec)
+    allowed = {'baseline', 'candidate', 'backend', 'local_root', 'timeout_seconds',
+               'max_stage_attempts', 'label', 'input_id'}
+    if not isinstance(spec, dict) or set(spec) - allowed:
+        raise ValueError('Unknown experiment fields')
+    for key in ('backend', 'local_root', 'baseline', 'candidate'):
+        if key not in spec:
+            raise ValueError(f'Missing {key}')
+    strings(spec['backend'], 'backend', True)
+    local = Path(spec['local_root']).expanduser()
+    if not local.is_absolute():
+        raise ValueError('local_root must be an absolute node-local path')
+    spec['local_root'] = str(local)
+    for name in ('baseline', 'candidate'):
+        workload = spec[name]
+        if not isinstance(workload, dict) or set(workload) - {'cwd', 'launcher', 'script', 'args', 'env', 'ranks'}:
+            raise ValueError(f'Unknown {name} workload fields')
+        cwd = Path(workload['cwd']).expanduser().resolve()
+        if not cwd.is_dir():
+            raise ValueError(f'{name}.cwd does not exist')
+        script = (cwd / workload['script']).resolve()
+        if cwd not in script.parents or not script.is_file():
+            raise ValueError(f'{name}.script must be a file inside its checkout')
+        workload.update(cwd=str(cwd), script=str(script))
+        strings(workload['launcher'], name + '.launcher', True)
+        strings(workload.setdefault('args', []), name + '.args')
+        env = workload.setdefault('env', {})
+        if not isinstance(env, dict) or any(not isinstance(k, str) or not isinstance(v, str)
+                                           or '=' in k or '\0' in k + v for k, v in env.items()):
+            raise ValueError('env must contain string keys and values')
+        if RESERVED_ENV & env.keys():
+            raise ValueError('Output/lifecycle configuration belongs to the harness, not workload.env')
+        ranks = workload.setdefault('ranks', [0])
+        if not isinstance(ranks, list) or not ranks or any(type(r) is not int or r < 0 for r in ranks) or len(set(ranks)) != len(ranks):
+            raise ValueError('ranks must be distinct nonnegative integers')
+        workload['ranks'] = sorted(ranks)
+    if spec['baseline']['cwd'] == spec['candidate']['cwd']:
+        raise ValueError('Use separate source checkouts for baseline and candidate')
+    if spec['baseline']['ranks'] != spec['candidate']['ranks']:
+        raise ValueError('v1 compares matching global ranks; rank remapping is not supported')
+    timeout = spec.setdefault('timeout_seconds', 3600)
+    attempts = spec.setdefault('max_stage_attempts', 2)
+    if type(timeout) not in (int, float) or not math.isfinite(timeout) or timeout <= 0:
+        raise ValueError('timeout_seconds must be positive and finite')
+    if type(attempts) is not int or not 1 <= attempts <= 10:
+        raise ValueError('max_stage_attempts must be between 1 and 10')
+    return spec