opguard-harness 0.1.0__tar.gz

opguard_harness-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

opguard_harness-0.1.0/PKG-INFO

@@ -0,0 +1,34 @@
+Metadata-Version: 2.4
+Name: opguard-harness
+Version: 0.1.0
+Summary: Diagnostic skills and supporting agent tools for OpGuard
+License-Expression: Apache-2.0
+Project-URL: Repository, https://github.com/OrderLab/OpGuard
+Project-URL: Documentation, https://github.com/OrderLab/OpGuard/blob/main/harness/doc/Usage.md
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# OpGuard Harness
+
+Give your coding agent [OpGuard](https://github.com/OrderLab/OpGuard) tools to investigate why two training runs differ.
+
+```bash
+python -m pip install opguard-harness
+opguard-harness tools
+```
+
+Then ask your coding agent:
+
+> Use OpGuard to investigate these two runs: `./run-a/train.py` and `./run-b/train.py`.
+> My training Python is `/path/to/train-env/bin/python`.
+> Run `opguard-harness tools` to discover the tools, and explain the evidence you find.
+
+Requires Python 3.10+. Works with coding agents that can run shell commands. Install OpGuard separately in the training environment; the harness has no runtime dependencies.
+
+[Installation details](https://github.com/OrderLab/OpGuard/blob/main/harness/doc/Usage.md#install).
+
+[Agent setup and tool calls](https://github.com/OrderLab/OpGuard/blob/main/harness/doc/Usage.md#agent-integration) · [Diagnostic skills](https://github.com/OrderLab/OpGuard/blob/main/harness/skills/investigate-first-diff/SKILL.md) · [Example experiment](https://github.com/OrderLab/OpGuard/blob/main/harness/examples/experiment.json) · [Walkthrough](https://github.com/OrderLab/OpGuard/blob/main/harness/examples/demo_case5/README.md)
+
+[Apache-2.0](https://github.com/OrderLab/OpGuard/blob/main/harness/LICENSE).

opguard_harness-0.1.0/README.md

@@ -0,0 +1,22 @@
+# OpGuard Harness
+
+Give your coding agent [OpGuard](https://github.com/OrderLab/OpGuard) tools to investigate why two training runs differ.
+
+```bash
+python -m pip install opguard-harness
+opguard-harness tools
+```
+
+Then ask your coding agent:
+
+> Use OpGuard to investigate these two runs: `./run-a/train.py` and `./run-b/train.py`.
+> My training Python is `/path/to/train-env/bin/python`.
+> Run `opguard-harness tools` to discover the tools, and explain the evidence you find.
+
+Requires Python 3.10+. Works with coding agents that can run shell commands. Install OpGuard separately in the training environment; the harness has no runtime dependencies.
+
+[Installation details](https://github.com/OrderLab/OpGuard/blob/main/harness/doc/Usage.md#install).
+
+[Agent setup and tool calls](https://github.com/OrderLab/OpGuard/blob/main/harness/doc/Usage.md#agent-integration) · [Diagnostic skills](https://github.com/OrderLab/OpGuard/blob/main/harness/skills/investigate-first-diff/SKILL.md) · [Example experiment](https://github.com/OrderLab/OpGuard/blob/main/harness/examples/experiment.json) · [Walkthrough](https://github.com/OrderLab/OpGuard/blob/main/harness/examples/demo_case5/README.md)
+
+[Apache-2.0](https://github.com/OrderLab/OpGuard/blob/main/harness/LICENSE).

opguard_harness-0.1.0/opguard_harness/__init__.py

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

opguard_harness-0.1.0/opguard_harness/__main__.py

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

opguard_harness-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/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