Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 21 additions & 0 deletions docs/DOWNSTREAM_SNAPSHOT_BINDING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
# Downstream snapshot identity

The active `portable/CANDIDATE_DOWNSTREAM_GATE_STUBS.json` describes one recorded Math snapshot. Its `math_tip` must be a lowercase 40-hex commit string, and every artifact whose `repository` is `Math-` must use that exact `commit`. Byte equality at a different commit does not satisfy this declaration.

The canonical verifier preflights the whole downstream bundle before candidate rows are returned or deduplicated, and before the direct tip-check path performs any remote fetch. Refusals identify `math_tip`; they are distinct from `TIP_DRIFT`, which reports changed live bytes.

The rule is scoped to this named bundle. Other candidate bundles and the standalone RN stub retain their existing per-row commit identities. Non-Math rows retain their existing identity rules. A coherent historical snapshot remains a valid recorded identity; neither the current Math commit nor a minimum date is hardcoded. The existing empty-bundle behavior is preserved when its declared tip is valid. Frozen history files are outside active discovery.

## Verification and limits

The checkout-only regression module `tests/test_stub_verify_snapshot.py` exercises both public entry paths, a second-row mismatch before any fetch, duplicate-key hiding, malformed tip declarations independent of row comparisons, and positive compatibility cases. Its synthetic references establish string/association behavior, not real commit existence. Existing wrong-byte and wrong-length controls remain separate.

Test-first evidence: tests-only head `5b9eae7b7ad2cd1cb45f093bd9f55087102b1a8e`, hosted run [38074388202](https://github.com/d6g8k5htny-coder/query-/actions/runs/38074388202), tested merge `b07128dfc9921d02505700616dc3fb94dcc8dcca`: 38 legacy tests passed; package discovery ran 74 methods and had 50 expected missing-refusal assertion failures, with no test errors. The production fix follows that observed RED. Current final verification and nonauthor disposition belong to [PR37](https://github.com/d6g8k5htny-coder/query-/pull/37).

Run the existing complete legacy and package commands in AGENTS.md, then both portable verifier commands in the existing hosted workflow. The custom source archive retains its five-module/15-method subset; this new checkout regression module does not change archive membership. No runtime dependency is added.

Pinned-byte verification authenticates bytes at declared commits. The optional tip check still compares sequential reads of floating `main` against those byte identities; it does not authenticate an observed atomic live snapshot. Direct tip checking alone does not establish the declared commit's existence. Internal injected loader seams intentionally bypass on-disk discovery and are not evidence that a real bundle was validated.

Scientific effect is NONE. Snapshot consistency, byte identity, hosted CI and a registered handoff are engineering evidence, not catalog integration, theorem acceptance or proof completion.

Authorship: OpenAI/Codex root01a0bbb5, delegated for Dylan Roy; source-exposed, organizational-independence credit0. No personal human review is claimed.
11 changes: 11 additions & 0 deletions src/universal_law_query/stub_verify.py
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,15 @@
REPO_ROOT=Path(__file__).resolve().parents[2]
PUBLIC_REPOS={'Math-','google-drive','governance-','main','meta-framework','query-','trial'}

def _validate_downstream_snapshot(data:dict)->None:
"""Bind Math rows to the declared snapshot, independently of byte equality."""
math_tip=data.get('math_tip')
if not isinstance(math_tip,str) or not re.fullmatch('[0-9a-f]{40}',math_tip):
raise SystemExit('REFUSED: downstream math_tip must be an exact lowercase commit')
for row in data['artifacts']:
if row.get('repository')=='Math-' and row.get('commit')!=math_tip:
raise SystemExit('REFUSED: downstream Math- commit must match math_tip for '+row.get('key','?'))

def load_candidates(root: Path|None=None)->list[dict]:
root=REPO_ROOT if root is None else Path(root)
portable=root/'portable';rows=[]
Expand All @@ -13,6 +22,7 @@ def load_candidates(root: Path|None=None)->list[dict]:
for bundle_path in sorted(portable.glob('CANDIDATE_*.json')):
data=json.loads(bundle_path.read_text())
if data.get('scientific_status_authority') is not False: raise SystemExit('REFUSED: candidate bundle must deny scientific authority: '+bundle_path.name)
if bundle_path.name=='CANDIDATE_DOWNSTREAM_GATE_STUBS.json': _validate_downstream_snapshot(data)
rows.extend(data['artifacts'])
seen=set();out=[]
for row in rows:
Expand Down Expand Up @@ -42,6 +52,7 @@ def check_math_tip_drift(root:Path|None=None, *, fetch_raw_fn=None)->dict:
bundle_path=root/'portable/CANDIDATE_DOWNSTREAM_GATE_STUBS.json'
if not bundle_path.is_file(): return {'checked':[],'drifted':[],'math_tip_recorded':None}
data=json.loads(bundle_path.read_text());drifted=[];checked=[]
_validate_downstream_snapshot(data)
for row in data['artifacts']:
validate_row(row)
try: tip_raw=fetch_raw_fn(row['repository'],'main',row['path'],10000000)
Expand Down
4 changes: 2 additions & 2 deletions test_verify_portable_stubs.py
Original file line number Diff line number Diff line change
Expand Up @@ -81,7 +81,7 @@ def test_math_tip_check_no_drift_when_tip_matches(self):
payload = b'data'
fake = {
'scientific_status_authority': False,
'math_tip': 'tipsha',
'math_tip': '1' * 40,
'artifacts': [self._gate_row(payload)],
}
with mock.patch.object(v, 'fetch_raw', return_value=payload):
Expand All @@ -94,7 +94,7 @@ def test_math_tip_check_no_drift_when_tip_matches(self):
def test_math_tip_check_detects_drift(self):
fake = {
'scientific_status_authority': False,
'math_tip': 'tipsha',
'math_tip': '1' * 40,
'artifacts': [self._gate_row(b'data')],
}
with mock.patch.object(v, 'fetch_raw', return_value=b'DIFF'):
Expand Down
189 changes: 189 additions & 0 deletions tests/test_stub_verify_snapshot.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,189 @@
"""Downstream bundle snapshot identity, separate from byte equality or tip drift."""
from __future__ import annotations

import contextlib
import hashlib
import io
import json
import os
import sys
import tempfile
import unittest
from pathlib import Path
from unittest import mock

ROOT = Path(__file__).resolve().parents[1]
sys.path.insert(0, str(ROOT / 'src'))
from universal_law_query import stub_verify as verifier

# Synthetic immutable-reference shapes; no existence or live snapshot claim.
SNAPSHOT = 'a' * 40
OLDER = 'b' * 40
PAYLOAD = b'unchanged README bytes\n'
BUNDLE = 'CANDIDATE_DOWNSTREAM_GATE_STUBS.json'


def row(key, commit=SNAPSHOT):
return {
'key': key, 'repository': 'Math-', 'visibility': 'public',
'commit': commit, 'path': 'frontiers/example/' + key + '.md',
'bytes': len(PAYLOAD), 'sha256': hashlib.sha256(PAYLOAD).hexdigest(),
}


class DownstreamSnapshotTests(unittest.TestCase):
def setUp(self):
self.scratch = tempfile.TemporaryDirectory()
self.addCleanup(self.scratch.cleanup)
self.root = Path(self.scratch.name)
self.portable = self.root / 'portable'
self.portable.mkdir()

def write_bundle(self, data, name=BUNDLE):
(self.portable / name).write_text(json.dumps(data), encoding='utf-8')

def bundle(self, tip=SNAPSHOT):
return {'scientific_status_authority': False, 'math_tip': tip,
'artifacts': [row('first', tip), row('readme', tip)]}

def test_coherent_current_and_historical_snapshots_are_valid(self):
# No hardcoded current main requirement: each coherent snapshot is valid.
for tip in (SNAPSHOT, OLDER):
with self.subTest(tip=tip):
data = self.bundle(tip)
self.write_bundle(data)
self.assertEqual(verifier.load_candidates(self.root), data['artifacts'])
result = verifier.check_math_tip_drift(
self.root, fetch_raw_fn=lambda *args: PAYLOAD)
self.assertEqual(result['math_tip_recorded'], tip)
self.assertEqual(result['checked'], ['first', 'readme'])
self.assertEqual(result['drifted'], [])

def test_same_bytes_at_different_commit_are_rejected_by_loader(self):
data = self.bundle()
# Alter only the second row's commit. Digest/length/bytes stay correct.
data['artifacts'][1]['commit'] = OLDER
self.write_bundle(data)
with self.assertRaisesRegex(SystemExit, 'REFUSED:.*math_tip'):
verifier.load_candidates(self.root)

def test_cli_rejects_mixed_snapshot_before_any_pinned_fetch(self):
data = self.bundle()
data['artifacts'][1]['commit'] = OLDER
self.write_bundle(data)
fetch = mock.Mock(return_value=PAYLOAD)
with mock.patch.dict(os.environ, {'QUERY_STUB_VERIFY': '1'}), \
contextlib.redirect_stdout(io.StringIO()), \
self.assertRaisesRegex(SystemExit, 'REFUSED:.*math_tip'):
verifier.main([], load_candidates_fn=lambda: verifier.load_candidates(self.root),
fetch_fn=fetch)
fetch.assert_not_called()

def test_direct_tip_check_preflights_all_rows_before_any_fetch(self):
data = self.bundle()
data['artifacts'][1]['commit'] = OLDER
self.write_bundle(data)
fetch = mock.Mock(return_value=PAYLOAD)
with self.assertRaisesRegex(SystemExit, 'REFUSED:.*math_tip'):
verifier.check_math_tip_drift(self.root, fetch_raw_fn=fetch)
fetch.assert_not_called()

def test_missing_or_malformed_snapshot_is_refused_on_both_paths(self):
for value in ('MISSING', None, 7, True, [], {}, '', 'main',
'a' * 39, 'a' * 41, 'A' * 40, 'G' * 40):
with self.subTest(value=value):
data = self.bundle()
if value == 'MISSING':
del data['math_tip']
else:
data['math_tip'] = value
self.write_bundle(data)
with self.subTest(entrypoint='loader'):
with self.assertRaisesRegex(SystemExit, 'REFUSED:.*math_tip'):
verifier.load_candidates(self.root)
with self.subTest(entrypoint='direct-tip'):
fetch = mock.Mock(return_value=PAYLOAD)
with self.assertRaisesRegex(SystemExit, 'REFUSED:.*math_tip'):
verifier.check_math_tip_drift(self.root, fetch_raw_fn=fetch)
fetch.assert_not_called()

def test_tip_format_is_checked_even_without_rows(self):
# Commit comparisons cannot substitute for validating the declaration.
for value in (None, 7, True, [], {}, '', 'main',
'a' * 39, 'a' * 41, 'A' * 40, 'G' * 40):
with self.subTest(value=value):
self.write_bundle({'scientific_status_authority': False,
'math_tip': value, 'artifacts': []})
with self.subTest(entrypoint='loader'):
with self.assertRaisesRegex(SystemExit, 'REFUSED:.*math_tip'):
verifier.load_candidates(self.root)
with self.subTest(entrypoint='direct-tip'):
fetch = mock.Mock(return_value=PAYLOAD)
with self.assertRaisesRegex(SystemExit, 'REFUSED:.*math_tip'):
verifier.check_math_tip_drift(self.root, fetch_raw_fn=fetch)
fetch.assert_not_called()

def test_empty_coherent_bundle_keeps_existing_behavior(self):
self.write_bundle({'scientific_status_authority': False,
'math_tip': SNAPSHOT, 'artifacts': []})
self.assertEqual(verifier.load_candidates(self.root), [])
result = verifier.check_math_tip_drift(
self.root, fetch_raw_fn=lambda *args: self.fail('unexpected fetch'))
self.assertEqual(result['checked'], [])
self.assertEqual(result['drifted'], [])
self.assertEqual(result['math_tip_recorded'], SNAPSHOT)

def test_other_repository_commit_is_not_bound_to_math_snapshot(self):
data = self.bundle()
data['artifacts'][1]['repository'] = 'main'
data['artifacts'][1]['commit'] = OLDER
self.write_bundle(data)
self.assertEqual(verifier.load_candidates(self.root), data['artifacts'])
result = verifier.check_math_tip_drift(self.root, fetch_raw_fn=lambda *args: PAYLOAD)
self.assertEqual(result['drifted'], [])

def test_duplicate_key_does_not_hide_inconsistent_snapshot(self):
data = self.bundle()
data['artifacts'][1]['key'] = 'first'
data['artifacts'][1]['commit'] = OLDER
self.write_bundle(data)
with self.assertRaisesRegex(SystemExit, 'REFUSED:.*math_tip'):
verifier.load_candidates(self.root)

def test_current_checkout_retains_ten_unique_candidate_keys(self):
keys = [item['key'] for item in verifier.load_candidates(ROOT)]
self.assertEqual(len(keys), 10)
self.assertEqual(len(set(keys)), 10)
self.assertIn('downstream-hard-gate', keys)
self.assertEqual(keys.count('rn-fixed-remote-window-replay'), 1)

def test_other_public_and_single_stub_formats_keep_distinct_commits(self):
public = {'scientific_status_authority': False,
'artifacts': [row('public-a', SNAPSHOT), row('public-b', OLDER)]}
self.write_bundle(public, 'CANDIDATE_PUBLIC_REPLAY_STUBS.json')
single = row('rn-single', '1' * 40)
self.write_bundle(single, 'RN_FIXED_REMOTE_REPLAY_STUB.json')
self.assertEqual(verifier.load_candidates(self.root), [single, *public['artifacts']])
fetch = mock.Mock(return_value=PAYLOAD)
self.assertEqual(verifier.check_math_tip_drift(self.root, fetch_raw_fn=fetch),
{'checked': [], 'drifted': [], 'math_tip_recorded': None})
fetch.assert_not_called()

def test_snapshot_identity_does_not_hide_real_tip_byte_drift(self):
self.write_bundle(self.bundle())
result = verifier.check_math_tip_drift(
self.root, fetch_raw_fn=lambda *args: b'changed current main bytes\n')
self.assertEqual(result['math_tip_recorded'], SNAPSHOT)
self.assertEqual([item['key'] for item in result['drifted']], ['first', 'readme'])

def test_frozen_history_is_not_loaded_as_current_candidate(self):
self.write_bundle(self.bundle())
history = self.portable / 'history'
history.mkdir()
(history / BUNDLE).write_text('{"historical": "not a current candidate"}')
self.assertEqual([item['key'] for item in verifier.load_candidates(self.root)],
['first', 'readme'])


if __name__ == '__main__':
unittest.main()
Loading