velographx 0.8.2__tar.gz

velographx-0.8.2/.github/CODEOWNERS

@@ -0,0 +1,8 @@
+# Security-sensitive repository surfaces
+/.github/workflows/ @sauravsingla
+/SECURITY.md @sauravsingla
+/docs/enterprise-security.md @sauravsingla
+/tools/security_scan.py @sauravsingla
+/tools/generate_spdx_sbom.py @sauravsingla
+/.github/dependabot.yml @sauravsingla
+/.github/CODEOWNERS @sauravsingla

velographx-0.8.2/.github/ISSUE_TEMPLATE/security.md

@@ -0,0 +1,13 @@
+---
+name: Security vulnerability
+description: Guidance for reporting a suspected security vulnerability
+title: ""
+labels: []
+assignees: []
+---
+
+Please do **not** disclose suspected vulnerabilities, exploit details, credentials, proprietary data, or sensitive information in a public issue.
+
+Follow the private reporting guidance in [SECURITY.md](../../SECURITY.md).
+
+If private vulnerability reporting is enabled for this repository, use GitHub's private security reporting flow.

velographx-0.8.2/.github/dependabot.yml

@@ -0,0 +1,14 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+    groups:
+      codeql-action:
+        patterns:
+          - "github/codeql-action/*"
+    labels:
+      - dependencies
+      - security

velographx-0.8.2/.github/workflows/adaptive-policy-ablation.yml

@@ -0,0 +1,148 @@
+name: Adaptive BFS Policy Ablation
+
+on:
+  push:
+    paths:
+      - '.github/workflows/adaptive-policy-ablation.yml'
+      - 'benchmarks/adaptive_policy_bfs.cpp'
+      - 'tools/summarize_adaptive_policy.py'
+      - 'tools/prepare_dataset.py'
+      - 'tools/prepare_pinned_edge_stream.py'
+      - 'tools/prepare_symmetric_pinned_edge_stream.py'
+      - 'datasets/manifest.public-small.json'
+      - 'include/velographx/incremental/bfs.hpp'
+      - 'include/velographx/storage/**'
+  workflow_dispatch:
+
+jobs:
+  policy-ablation:
+    runs-on: ubuntu-22.04
+    timeout-minutes: 120
+    env:
+      OMP_NUM_THREADS: '1'
+      OMP_PROC_BIND: 'true'
+      SIMPLE_UPDATE_FRACTION: '0.01'
+      EPINIONS_TEXT_SHA256: 3e42b000e66cada74053ac7f8b24de291f9837264421dc2f3730b45cc58d17b1
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install build and plotting dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends ninja-build
+          python -m pip install --disable-pip-version-check matplotlib
+
+      - name: Build VeloGraphX and policy harness
+        run: |
+          cmake -S . -B build/vx -G Ninja -DCMAKE_BUILD_TYPE=Release -DVELOGRAPHX_BUILD_TESTS=OFF -DVELOGRAPHX_BUILD_BENCHMARKS=ON
+          cmake --build build/vx --target velographx_external_risgraph_bfs -j 2
+          c++ -O3 -DNDEBUG -std=c++20 -Iinclude benchmarks/adaptive_policy_bfs.cpp build/vx/libvelographx.a -pthread -o build/adaptive_policy_bfs
+
+      - name: Prepare three checksum-pinned graph families
+        run: |
+          mkdir -p build/policy/datasets build/policy/runs build/policy/summary
+
+          python tools/prepare_dataset.py --manifest datasets/manifest.public-small.json --output-dir build/policy/datasets --dataset web-Google > build/policy/web-Google-source.json
+          python tools/prepare_dataset.py --manifest datasets/manifest.public-small.json --output-dir build/policy/datasets --dataset ca-GrQc > build/policy/ca-GrQc-source.json
+          python tools/prepare_dataset.py --manifest datasets/manifest.public-small.json --output-dir build/policy/datasets --dataset soc-Epinions1 > build/policy/soc-Epinions1-source.json
+
+          python tools/prepare_pinned_edge_stream.py \
+            --input build/policy/datasets/web-Google.txt \
+            --output build/policy/web-Google.txt \
+            --report build/policy/web-Google-normalization.json \
+            --expected-sha256 8c0f453f1eb1e24ad145e36e542b129083237e96e585abae768927bdb70167d1 \
+            --expected-vertices 875713 --expected-edges 5105039
+
+          python tools/prepare_symmetric_pinned_edge_stream.py \
+            --input build/policy/datasets/ca-GrQc.txt \
+            --output build/policy/ca-GrQc.txt \
+            --report build/policy/ca-GrQc-normalization.json \
+            --expected-sha256 513efa8bb5c6d3d739797ca028d4a26a7df6bc20adcf3e722e18d1bcdb0e62d5 \
+            --expected-vertices 5242 --expected-source-rows 28980 --expected-self-loops 12 \
+            --expected-nonloop-pair-multiplicity 2 --expected-unique-nonloop-pairs 14484
+
+          gzip -dc build/policy/datasets/soc-Epinions1.gz > build/policy/epinions-source.txt
+          test "$(sha256sum build/policy/epinions-source.txt | awk '{print $1}')" = "$EPINIONS_TEXT_SHA256"
+          python tools/prepare_pinned_edge_stream.py \
+            --input build/policy/epinions-source.txt \
+            --output build/policy/soc-Epinions1.txt \
+            --report build/policy/soc-Epinions1-normalization.json \
+            --expected-sha256 "$EPINIONS_TEXT_SHA256" \
+            --expected-vertices 75879 --expected-edges 508837
+
+      - name: Run four-policy sweep with five repetitions
+        run: |
+          python - <<'PY'
+          import json, os, subprocess
+          from pathlib import Path
+
+          configs = {
+              'ca-GrQc': {'root':4282, 'rate':0.75, 'batches':[32,128,512,2048], 'min_reachable':1000},
+              'soc-Epinions1': {'root':763, 'rate':0.90, 'batches':[128,512,2048,8192], 'min_reachable':20000},
+              'web-Google': {'root':481807, 'rate':0.99, 'batches':[512,2048,8192,32768], 'min_reachable':100000},
+          }
+          for dataset,cfg in configs.items():
+              for batch in cfg['batches']:
+                  for rep in range(1,6):
+                      out = Path(f'build/policy/runs/{dataset}__{batch}__{rep}.json')
+                      with out.open('w') as f:
+                          subprocess.run([
+                              'build/adaptive_policy_bfs', f'build/policy/{dataset}.txt', str(cfg['root']),
+                              str(cfg['rate']), str(batch), os.environ['SIMPLE_UPDATE_FRACTION']
+                          ], stdout=f, check=True)
+                      d=json.load(out.open())
+                      assert d['all_policies_exact'], (dataset,batch,rep)
+                      assert all(p['exact'] for p in d['policies'])
+          PY
+
+      - name: Summarize crossover and oracle regret
+        run: |
+          python tools/summarize_adaptive_policy.py --input-dir build/policy/runs --output-dir build/policy/summary | tee build/policy/summary/stdout-summary.json
+          python - <<'PY'
+          import json
+          d=json.load(open('build/policy/summary/summary.json'))
+          assert d['all_results_exact']
+          assert set(d['datasets']) == {'ca-GrQc','soc-Epinions1','web-Google'}
+          for name,row in d['datasets'].items():
+              assert row['regimes'] == 4, (name,row)
+          PY
+
+      - name: Capture immutable evidence pins
+        run: |
+          {
+            echo "velographx_sha=$(git rev-parse HEAD)"
+            echo "web_google_source_sha256=8c0f453f1eb1e24ad145e36e542b129083237e96e585abae768927bdb70167d1"
+            echo "ca_grqc_source_sha256=513efa8bb5c6d3d739797ca028d4a26a7df6bc20adcf3e722e18d1bcdb0e62d5"
+            echo "epinions_gzip_sha256=69a2dab71fa5e3a0715487599fc16ca17ddc847379325a6c765bbad6e3e36938"
+            echo "epinions_text_sha256=$EPINIONS_TEXT_SHA256"
+            echo "simple_update_fraction=$SIMPLE_UPDATE_FRACTION"
+            echo "repetitions_per_regime=5"
+            echo "one_thread=true"
+          } > build/policy/pins.txt
+          python - <<'PY' >> build/policy/pins.txt
+          import json
+          from pathlib import Path
+
+          paths = sorted(Path('build/policy/runs').glob('*.json'))
+          if not paths:
+              raise SystemExit('no policy result available for threshold pinning')
+          first = json.loads(paths[0].read_text())
+          thresholds = first.get('thresholds')
+          if not isinstance(thresholds, dict) or not thresholds:
+              raise SystemExit('policy result does not contain selector thresholds')
+          for path in paths[1:]:
+              current = json.loads(path.read_text()).get('thresholds')
+              if current != thresholds:
+                  raise SystemExit(f'selector thresholds changed within run: {path}')
+          for key in sorted(thresholds):
+              print(f'selector_{key}={thresholds[key]}')
+          PY
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: adaptive-bfs-policy-ablation
+          path: build/policy/
+          retention-days: 90

velographx-0.8.2/.github/workflows/adaptive-policy-fifth-dataset-evaluation.yml

@@ -0,0 +1,115 @@
+name: Adaptive BFS Amazon0302 Frozen One-Shot Evaluation
+on:
+  workflow_dispatch:
+
+jobs:
+  frozen-evaluation:
+    runs-on: ubuntu-22.04
+    timeout-minutes: 120
+    env:
+      OMP_NUM_THREADS: '1'
+      OMP_PROC_BIND: 'true'
+      FROZEN_SELECTOR_COMMIT: '4381113005c221e6db2c19bac753a57d872e6374'
+      FROZEN_BENCHMARK_BLOB: 'c30f3459d22e61fb95abdb077aa2fd0eda445690'
+      AMAZON_GZIP_SHA256: '5f1071ac04203b1bc8fc4af5fb473818a180ff1b97e3d7bd716d789801d1f2a3'
+      AMAZON_NORMALIZED_SHA256: '12fe44abf64966ad08b371bf4befd96df6aa8cd129ecb800dd6cc5dc1a753d30'
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          ref: '4381113005c221e6db2c19bac753a57d872e6374'
+      - uses: actions/setup-python@v5
+        with: {python-version: '3.12'}
+      - name: Verify frozen selector source
+        run: |
+          test "$(git rev-parse HEAD)" = "$FROZEN_SELECTOR_COMMIT"
+          test "$(git rev-parse HEAD:benchmarks/adaptive_policy_bfs.cpp)" = "$FROZEN_BENCHMARK_BLOB"
+          grep -q 'scale-conditioned-selector-owned-v3' benchmarks/adaptive_policy_bfs.cpp
+          grep -q 'vertices >= 200000' benchmarks/adaptive_policy_bfs.cpp
+      - name: Build frozen source unchanged
+        run: |
+          sudo apt-get update && sudo apt-get install -y --no-install-recommends ninja-build
+          cmake -S . -B build/fifth -G Ninja -DCMAKE_BUILD_TYPE=Release -DVELOGRAPHX_BUILD_TESTS=OFF
+          cmake --build build/fifth -j2
+          c++ -O3 -DNDEBUG -std=c++20 -Iinclude benchmarks/adaptive_policy_bfs.cpp build/fifth/libvelographx.a -pthread -o build/adaptive_policy_bfs
+      - name: Acquire and verify frozen amazon0302
+        run: |
+          mkdir -p build/amazon-one-shot/runs build/amazon-one-shot/summary
+          curl --fail --location --retry 3 https://snap.stanford.edu/data/amazon0302.txt.gz -o build/amazon-one-shot/amazon0302.txt.gz
+          test "$(sha256sum build/amazon-one-shot/amazon0302.txt.gz | awk '{print $1}')" = "$AMAZON_GZIP_SHA256"
+          gzip -dc build/amazon-one-shot/amazon0302.txt.gz > build/amazon-one-shot/raw.txt
+          python - <<'PY'
+          ids={}; edges=[]
+          for line in open('build/amazon-one-shot/raw.txt'):
+            if not line.strip() or line[0]=='#': continue
+            a,b=line.split()[:2]
+            if a not in ids: ids[a]=len(ids)
+            if b not in ids: ids[b]=len(ids)
+            edges.append((ids[a],ids[b]))
+          assert len(ids)==262111,(len(ids),len(edges))
+          assert len(edges)==1234877,(len(ids),len(edges))
+          with open('build/amazon-one-shot/amazon0302.txt','w') as f:
+            for a,b in edges: f.write(f'{a} {b}\n')
+          PY
+          test "$(sha256sum build/amazon-one-shot/amazon0302.txt | awk '{print $1}')" = "$AMAZON_NORMALIZED_SHA256"
+          sha256sum build/amazon-one-shot/amazon0302.txt.gz build/amazon-one-shot/raw.txt build/amazon-one-shot/amazon0302.txt > build/amazon-one-shot/checksums.txt
+      - name: Frozen one-shot performance evaluation
+        run: |
+          python - <<'PY'
+          import json,subprocess
+          from pathlib import Path
+          roots=[20802,99851,0]
+          batches=[512,2048,8192]
+          for root in roots:
+            for batch in batches:
+              for rep in range(1,6):
+                p=Path(f'build/amazon-one-shot/runs/amazon0302-r{root}__{batch}__{rep}.json')
+                with p.open('w') as f:
+                  subprocess.run(['build/adaptive_policy_bfs','build/amazon-one-shot/amazon0302.txt',str(root),'0.90',str(batch),'0.01'],stdout=f,check=True)
+                d=json.load(p.open())
+                assert d['selector']=='scale-conditioned-selector-owned-v3'
+                assert d['selector_feature_cost_included_in_adaptive_timing']
+                assert d['all_policies_exact']
+          PY
+      - name: Fixed publication acceptance
+        run: |
+          python - <<'PY'
+          import glob,json,statistics
+          regs=[]; batch_reg=[]; decisions=[]; setups=[]; by_root={}; by_batch={}
+          all_exact=True
+          for fn in glob.glob('build/amazon-one-shot/runs/*.json'):
+            x=json.load(open(fn)); all_exact &= x['all_policies_exact']
+            ps={p['name']:p for p in x['policies']}; a=ps['adaptive']
+            decisions.append(a['mean_decision_us']); setups.append(a['selector_setup_us'])
+            best=min(p['total_us'] for p in ps.values()); rr=a['total_us']/best-1; regs.append(rr)
+            root=str(x['root']); batch=str(x['batch_size'])
+            by_root.setdefault(root,[]).append(rr); by_batch.setdefault(batch,[]).append(rr)
+            for i,v in enumerate(a['batch_us']):
+              b=min(p['batch_us'][i] for p in ps.values()); batch_reg.append(v/b-1)
+          batch_reg.sort(); p95=batch_reg[min(len(batch_reg)-1,int(.95*(len(batch_reg)-1)))]
+          m={
+            'dataset':'amazon0302','one_shot':True,'selector':'scale-conditioned-selector-owned-v3',
+            'frozen_selector_commit':'4381113005c221e6db2c19bac753a57d872e6374',
+            'frozen_benchmark_blob':'c30f3459d22e61fb95abdb077aa2fd0eda445690',
+            'all_exact':all_exact,'regimes':len(regs),
+            'mean_regret':statistics.mean(regs),'p95_batch_regret':p95,'worst_regime_regret':max(regs),
+            'mean_decision_us':statistics.mean(decisions),'mean_selector_setup_us':statistics.mean(setups),
+            'root_mean_regret':{k:statistics.mean(v) for k,v in by_root.items()},
+            'batch_mean_regret':{k:statistics.mean(v) for k,v in by_batch.items()},
+            'targets':{'exact':True,'mean_regret_max':0.05,'p95_batch_regret_max':0.20,'worst_regime_regret_max':0.25}
+          }
+          print(json.dumps(m,indent=2)); open('build/amazon-one-shot/summary/paper-metrics.json','w').write(json.dumps(m,indent=2)+'\n')
+          assert m['all_exact'],m
+          assert m['mean_regret']<=0.05,m
+          assert m['p95_batch_regret']<=0.20,m
+          assert m['worst_regime_regret']<=0.25,m
+          PY
+      - name: Frozen provenance
+        if: always()
+        run: |
+          { echo evaluation=amazon0302-one-shot; echo selector_commit=$FROZEN_SELECTOR_COMMIT; echo benchmark_blob=$FROZEN_BENCHMARK_BLOB; echo selector=scale-conditioned-selector-owned-v3; echo source_transformation=false; echo tuning_after_freeze=false; echo roots=20802,99851,0; echo batches=512,2048,8192; echo repetitions=5; echo import_rate=0.90; echo gzip_sha256=$AMAZON_GZIP_SHA256; echo normalized_sha256=$AMAZON_NORMALIZED_SHA256; echo fixed_targets='exact=100%,mean<=5%,p95<=20%,worst<=25%'; } > build/amazon-one-shot/provenance.txt
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: adaptive-amazon0302-frozen-one-shot
+          path: build/amazon-one-shot/
+          retention-days: 90

velographx-0.8.2/.github/workflows/adaptive-policy-fifth-dataset-freeze.yml

@@ -0,0 +1,78 @@
+name: Adaptive BFS Fifth Dataset Topology Freeze
+on:
+  push:
+    paths:
+      - '.github/workflows/adaptive-policy-fifth-dataset-freeze.yml'
+  workflow_dispatch:
+
+jobs:
+  freeze:
+    runs-on: ubuntu-22.04
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v5
+        with: {python-version: '3.12'}
+      - name: Acquire and validate SNAP amazon0302
+        run: |
+          mkdir -p build/fifth-freeze
+          curl --fail --location --retry 3 https://snap.stanford.edu/data/amazon0302.txt.gz -o build/fifth-freeze/amazon0302.txt.gz
+          gzip -dc build/fifth-freeze/amazon0302.txt.gz > build/fifth-freeze/raw.txt
+          python - <<'PY'
+          import hashlib,json
+          ids={};edges=[]
+          for line in open('build/fifth-freeze/raw.txt'):
+            if not line.strip() or line[0]=='#': continue
+            a,b=line.split()[:2]
+            if a not in ids: ids[a]=len(ids)
+            if b not in ids: ids[b]=len(ids)
+            edges.append((ids[a],ids[b]))
+          assert len(ids)==262111,(len(ids),len(edges))
+          assert len(edges)==1234877,(len(ids),len(edges))
+          with open('build/fifth-freeze/amazon0302.txt','w') as f:
+            for a,b in edges:f.write(f'{a} {b}\n')
+          print('validated',len(ids),len(edges))
+          PY
+          sha256sum build/fifth-freeze/amazon0302.txt.gz build/fifth-freeze/raw.txt build/fifth-freeze/amazon0302.txt > build/fifth-freeze/checksums.txt
+      - name: Topology-only root stratification
+        run: |
+          python - <<'PY'
+          import collections,json,math
+          path='build/fifth-freeze/amazon0302.txt'
+          edges=[];n=0
+          for line in open(path):
+            u,v=map(int,line.split());edges.append((u,v));n=max(n,u+1,v+1)
+          imported=int(len(edges)*0.90)
+          adj=[[] for _ in range(n)]
+          outdeg=[0]*n
+          for u,v in edges[:imported]:adj[u].append(v);outdeg[u]+=1
+          candidates=sorted(set(round(i*(n-1)/63) for i in range(64)))
+          def reach(root):
+            seen=bytearray(n);seen[root]=1;q=collections.deque([root]);count=1
+            while q:
+              u=q.popleft()
+              for v in adj[u]:
+                if not seen[v]:seen[v]=1;count+=1;q.append(v)
+            return count/n
+          scored=[{'root':r,'reachable_fraction':reach(r),'out_degree':outdeg[r]} for r in candidates]
+          ordered=sorted(scored,key=lambda x:(x['reachable_fraction'],x['out_degree'],x['root']))
+          picks=[]
+          for idx in [0,len(ordered)//2,len(ordered)-1]:
+            r=ordered[idx]
+            if r['root'] not in [x['root'] for x in picks]:picks.append(r)
+          if len(picks)<3:
+            for r in ordered:
+              if r['root'] not in [x['root'] for x in picks]:picks.append(r)
+              if len(picks)==3:break
+          freeze={'dataset':'amazon0302','selection_uses_performance_timings':False,'vertices':n,'edges':len(edges),'import_rate':0.90,'candidate_rule':'64 evenly spaced dense IDs','root_rule':'minimum, median, maximum initial reachable fraction; out-degree then ID tie-break','roots':picks,'batch_sizes':[512,2048,8192],'repetitions':5,'acceptance':{'exact':True,'mean_regret_max':0.05,'p95_batch_regret_max':0.20,'worst_regime_regret_max':0.25,'mean_decision_us_max':1.0}}
+          print(json.dumps(freeze,indent=2))
+          open('build/fifth-freeze/freeze.json','w').write(json.dumps(freeze,indent=2)+'\n')
+          PY
+      - name: Freeze provenance
+        run: |
+          { echo freeze_commit=$(git rev-parse HEAD); echo performance_timings_observed=false; echo prior_unseen_dataset=email-EuAll; echo fifth_dataset=amazon0302; } > build/fifth-freeze/provenance.txt
+      - uses: actions/upload-artifact@v4
+        with:
+          name: adaptive-fifth-dataset-topology-freeze
+          path: build/fifth-freeze/
+          retention-days: 90

velographx-0.8.2/.github/workflows/adaptive-policy-final-validation.yml

@@ -0,0 +1,95 @@
+name: Adaptive BFS Policy Final Validation
+
+on:
+  workflow_dispatch:
+
+jobs:
+  final-validation:
+    runs-on: ubuntu-22.04
+    timeout-minutes: 120
+    env:
+      OMP_NUM_THREADS: '1'
+      OMP_PROC_BIND: 'true'
+      SIMPLE_UPDATE_FRACTION: '0.01'
+      CANDIDATE_AFFECTED_FRACTION: '0.05'
+      EPINIONS_TEXT_SHA256: 3e42b000e66cada74053ac7f8b24de291f9837264421dc2f3730b45cc58d17b1
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - name: Install dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends ninja-build
+          python -m pip install --disable-pip-version-check matplotlib
+      - name: Build five-percent candidate harness
+        run: |
+          cmake -S . -B build/vx -G Ninja -DCMAKE_BUILD_TYPE=Release -DVELOGRAPHX_BUILD_TESTS=OFF -DVELOGRAPHX_BUILD_BENCHMARKS=ON
+          cmake --build build/vx --target velographx_external_risgraph_bfs -j 2
+          mkdir -p build/final-validation
+          sed 's/policy == "always_incremental" ? 2.0 : 0.35/policy == "always_incremental" ? 2.0 : 0.05/; s/adaptive_affected_fraction\\\":0.35/adaptive_affected_fraction\\\":0.05/' benchmarks/adaptive_policy_bfs.cpp > build/final-validation/adaptive_policy_bfs.cpp
+          grep -q '2.0 : 0.05' build/final-validation/adaptive_policy_bfs.cpp
+          c++ -O3 -DNDEBUG -std=c++20 -Iinclude build/final-validation/adaptive_policy_bfs.cpp build/vx/libvelographx.a -pthread -o build/adaptive_policy_bfs_final
+      - name: Prepare pinned datasets
+        run: |
+          mkdir -p build/final-validation/datasets build/final-validation/runs build/final-validation/summary
+          python tools/prepare_dataset.py --manifest datasets/manifest.public-small.json --output-dir build/final-validation/datasets --dataset web-Google > build/final-validation/web-source.json
+          python tools/prepare_dataset.py --manifest datasets/manifest.public-small.json --output-dir build/final-validation/datasets --dataset ca-GrQc > build/final-validation/ca-source.json
+          python tools/prepare_dataset.py --manifest datasets/manifest.public-small.json --output-dir build/final-validation/datasets --dataset soc-Epinions1 > build/final-validation/epinions-source.json
+          python tools/prepare_pinned_edge_stream.py --input build/final-validation/datasets/web-Google.txt --output build/final-validation/web-Google.txt --report build/final-validation/web-normalization.json --expected-sha256 8c0f453f1eb1e24ad145e36e542b129083237e96e585abae768927bdb70167d1 --expected-vertices 875713 --expected-edges 5105039
+          python tools/prepare_symmetric_pinned_edge_stream.py --input build/final-validation/datasets/ca-GrQc.txt --output build/final-validation/ca-GrQc.txt --report build/final-validation/ca-normalization.json --expected-sha256 513efa8bb5c6d3d739797ca028d4a26a7df6bc20adcf3e722e18d1bcdb0e62d5 --expected-vertices 5242 --expected-source-rows 28980 --expected-self-loops 12 --expected-nonloop-pair-multiplicity 2 --expected-unique-nonloop-pairs 14484
+          gzip -dc build/final-validation/datasets/soc-Epinions1.gz > build/final-validation/epinions-source.txt
+          test "$(sha256sum build/final-validation/epinions-source.txt | awk '{print $1}')" = "$EPINIONS_TEXT_SHA256"
+          python tools/prepare_pinned_edge_stream.py --input build/final-validation/epinions-source.txt --output build/final-validation/soc-Epinions1.txt --report build/final-validation/epinions-normalization.json --expected-sha256 "$EPINIONS_TEXT_SHA256" --expected-vertices 75879 --expected-edges 508837
+      - name: Run blind third-root regimes
+        run: |
+          python - <<'PY'
+          import json, os, subprocess
+          from pathlib import Path
+          configs = {
+              'ca-GrQc-r1974': ('ca-GrQc',1974,0.75,[96,384,1536]),
+              'soc-Epinions1-r71391': ('soc-Epinions1',71391,0.90,[384,1536,6144]),
+              'web-Google-r391806': ('web-Google',391806,0.99,[1536,6144,24576]),
+          }
+          for label,(dataset,root,rate,batches) in configs.items():
+              for batch in batches:
+                  for rep in range(1,6):
+                      out=Path(f'build/final-validation/runs/{label}__{batch}__{rep}.json')
+                      with out.open('w') as f:
+                          subprocess.run(['build/adaptive_policy_bfs_final',f'build/final-validation/{dataset}.txt',str(root),str(rate),str(batch),os.environ['SIMPLE_UPDATE_FRACTION']],stdout=f,check=True)
+                      d=json.load(out.open())
+                      assert d['all_policies_exact']
+                      assert all(p['exact'] for p in d['policies'])
+          PY
+      - name: Summarize blind validation
+        run: |
+          python tools/summarize_adaptive_policy.py --input-dir build/final-validation/runs --output-dir build/final-validation/summary | tee build/final-validation/summary/stdout-summary.json
+          python - <<'PY'
+          import json
+          d=json.load(open('build/final-validation/summary/summary.json'))
+          assert d['all_results_exact']
+          assert len(d['datasets']) == 3
+          for name,row in d['datasets'].items(): assert row['regimes'] == 3
+          adaptive=[r for r in d['rows'] if r['policy']=='adaptive']
+          mean_relative=sum(r['relative_to_regime_best'] for r in adaptive)/len(adaptive)
+          print('adaptive_mean_relative_to_regime_best_all=',mean_relative)
+          assert mean_relative <= 1.10, mean_relative
+          assert max(r['relative_to_regime_best'] for r in adaptive) <= 1.30
+          PY
+      - name: Capture final validation pins
+        run: |
+          {
+            echo "velographx_sha=$(git rev-parse HEAD)"
+            echo "calibration_run=33311896406"
+            echo "heldout_validation_run=33312313428"
+            echo "candidate_affected_fraction=$CANDIDATE_AFFECTED_FRACTION"
+            echo "third_roots=ca-GrQc:1974,soc-Epinions1:71391,web-Google:391806"
+            echo "repetitions_per_regime=5"
+            echo "one_thread=true"
+          } > build/final-validation/pins.txt
+      - uses: actions/upload-artifact@v4
+        with:
+          name: adaptive-bfs-policy-final-validation
+          path: build/final-validation/
+          retention-days: 90

velographx-0.8.2/.github/workflows/adaptive-policy-fourth-dataset.yml

@@ -0,0 +1,76 @@
+name: Adaptive BFS Fourth Dataset Frozen Evaluation
+on:
+  workflow_dispatch:
+jobs:
+  frozen-evaluation:
+    runs-on: ubuntu-22.04
+    timeout-minutes: 120
+    env: {OMP_NUM_THREADS: '1', OMP_PROC_BIND: 'true'}
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v5
+        with: {python-version: '3.12'}
+      - name: Build frozen selector
+        run: |
+          sudo apt-get update && sudo apt-get install -y --no-install-recommends ninja-build
+          python -m pip install --disable-pip-version-check matplotlib
+          cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release -DVELOGRAPHX_BUILD_TESTS=OFF
+          cmake --build build -j2
+          c++ -O3 -DNDEBUG -std=c++20 -Iinclude benchmarks/adaptive_policy_bfs.cpp build/libvelographx.a -pthread -o build/adaptive_policy_bfs
+      - name: Acquire unseen SNAP email-EuAll
+        run: |
+          mkdir -p build/fourth/runs build/fourth/summary
+          curl --fail --location --retry 3 https://snap.stanford.edu/data/email-EuAll.txt.gz -o build/fourth/email-EuAll.txt.gz
+          gzip -dc build/fourth/email-EuAll.txt.gz > build/fourth/raw.txt
+          python - <<'PY'
+          ids={}; edges=[]
+          for line in open('build/fourth/raw.txt'):
+            if not line.strip() or line[0]=='#': continue
+            a,b=line.split()[:2]
+            if a not in ids: ids[a]=len(ids)
+            if b not in ids: ids[b]=len(ids)
+            edges.append((ids[a],ids[b]))
+          assert len(ids)==265214 and len(edges)==420045,(len(ids),len(edges))
+          with open('build/fourth/email-EuAll.txt','w') as f:
+            for a,b in edges:f.write(f'{a} {b}\n')
+          print('vertices',len(ids),'edges',len(edges))
+          PY
+          sha256sum build/fourth/email-EuAll.txt.gz build/fourth/raw.txt build/fourth/email-EuAll.txt > build/fourth/checksums.txt
+      - name: Frozen evaluation
+        run: |
+          python - <<'PY'
+          import json,subprocess
+          from pathlib import Path
+          roots=[0,1000,10000]
+          batches=[256,1024,4096]
+          for root in roots:
+            for batch in batches:
+              for rep in range(1,6):
+                p=Path(f'build/fourth/runs/email-EuAll-r{root}__{batch}__{rep}.json')
+                with p.open('w') as f: subprocess.run(['build/adaptive_policy_bfs','build/fourth/email-EuAll.txt',str(root),'0.90',str(batch),'0.01'],stdout=f,check=True)
+                d=json.load(p.open()); assert d['all_policies_exact']
+          PY
+      - name: Publication metrics and fixed acceptance
+        run: |
+          python - <<'PY'
+          import glob,json,statistics
+          regs=[]; batch_reg=[]; matches=tot=0; decision=[]
+          for fn in glob.glob('build/fourth/runs/*.json'):
+            x=json.load(open(fn)); ps={p['name']:p for p in x['policies']}; a=ps['adaptive']; decision.append(a['mean_decision_us'])
+            totals={k:v['total_us'] for k,v in ps.items()}; best=min(totals.values()); regs.append(a['total_us']/best-1)
+            for i,v in enumerate(a['batch_us']):
+              bestb=min(p['batch_us'][i] for p in ps.values()); r=v/bestb-1;batch_reg.append(r);matches+=r<=.01;tot+=1
+          batch_reg.sort();p95=batch_reg[min(len(batch_reg)-1,int(.95*(len(batch_reg)-1)))]
+          m={'dataset':'email-EuAll','all_exact':True,'regimes':len(regs),'mean_regret':statistics.mean(regs),'p95_batch_regret':p95,'worst_regime_regret':max(regs),'oracle_match_within_1pct':matches/tot,'mean_decision_us':statistics.mean(decision),'targets':{'mean_regret':.05,'p95_batch_regret':.20,'worst_regime_regret':.25}}
+          print(json.dumps(m,indent=2));open('build/fourth/summary/paper-metrics.json','w').write(json.dumps(m,indent=2)+'\n')
+          assert m['mean_regret']<=.05,m
+          assert m['p95_batch_regret']<=.20,m
+          assert m['worst_regime_regret']<=.25,m
+          PY
+      - name: Freeze provenance
+        if: always()
+        run: |
+          { echo selector_commit=$(git rev-parse HEAD); echo dataset=email-EuAll; echo expected_vertices=265214; echo expected_edges=420045; echo roots=0,1000,10000; echo batches=256,1024,4096; echo repetitions=5; echo targets=mean5%,p95-20%,worst25%; } > build/fourth/provenance.txt
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with: {name: adaptive-fourth-dataset-frozen, path: build/fourth/, retention-days: 90}

velographx-0.8.2/.github/workflows/adaptive-policy-heldout-final.yml

@@ -0,0 +1,81 @@
+name: Adaptive BFS Policy Held-out Final
+on:
+  workflow_dispatch:
+jobs:
+  heldout:
+    runs-on: ubuntu-22.04
+    timeout-minutes: 120
+    env:
+      OMP_NUM_THREADS: '1'
+      OMP_PROC_BIND: 'true'
+      SIMPLE_UPDATE_FRACTION: '0.01'
+      EPINIONS_TEXT_SHA256: 3e42b000e66cada74053ac7f8b24de291f9837264421dc2f3730b45cc58d17b1
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v5
+        with: {python-version: '3.12'}
+      - name: Dependencies and build
+        run: |
+          sudo apt-get update && sudo apt-get install -y --no-install-recommends ninja-build
+          python -m pip install --disable-pip-version-check matplotlib
+          cmake -S . -B build/vx -G Ninja -DCMAKE_BUILD_TYPE=Release -DVELOGRAPHX_BUILD_TESTS=OFF -DVELOGRAPHX_BUILD_BENCHMARKS=ON
+          cmake --build build/vx --target velographx_external_risgraph_bfs -j 2
+          c++ -O3 -DNDEBUG -std=c++20 -Iinclude benchmarks/adaptive_policy_bfs.cpp build/vx/libvelographx.a -pthread -o build/adaptive_policy_bfs
+      - name: Prepare pinned datasets
+        run: |
+          mkdir -p build/heldout/datasets build/heldout/runs build/heldout/summary
+          python tools/prepare_dataset.py --manifest datasets/manifest.public-small.json --output-dir build/heldout/datasets --dataset web-Google >/dev/null
+          python tools/prepare_dataset.py --manifest datasets/manifest.public-small.json --output-dir build/heldout/datasets --dataset ca-GrQc >/dev/null
+          python tools/prepare_dataset.py --manifest datasets/manifest.public-small.json --output-dir build/heldout/datasets --dataset soc-Epinions1 >/dev/null
+          python tools/prepare_pinned_edge_stream.py --input build/heldout/datasets/web-Google.txt --output build/heldout/web-Google.txt --report build/heldout/web.json --expected-sha256 8c0f453f1eb1e24ad145e36e542b129083237e96e585abae768927bdb70167d1 --expected-vertices 875713 --expected-edges 5105039 >/dev/null
+          python tools/prepare_symmetric_pinned_edge_stream.py --input build/heldout/datasets/ca-GrQc.txt --output build/heldout/ca-GrQc.txt --report build/heldout/ca.json --expected-sha256 513efa8bb5c6d3d739797ca028d4a26a7df6bc20adcf3e722e18d1bcdb0e62d5 --expected-vertices 5242 --expected-source-rows 28980 --expected-self-loops 12 --expected-nonloop-pair-multiplicity 2 --expected-unique-nonloop-pairs 14484 >/dev/null
+          gzip -dc build/heldout/datasets/soc-Epinions1.gz > build/heldout/ep.txt
+          test "$(sha256sum build/heldout/ep.txt | awk '{print $1}')" = "$EPINIONS_TEXT_SHA256"
+          python tools/prepare_pinned_edge_stream.py --input build/heldout/ep.txt --output build/heldout/soc-Epinions1.txt --report build/heldout/ep.json --expected-sha256 "$EPINIONS_TEXT_SHA256" --expected-vertices 75879 --expected-edges 508837 >/dev/null
+      - name: Frozen unseen roots and update sizes
+        run: |
+          python - <<'PY'
+          import json,os,subprocess
+          from pathlib import Path
+          configs=[
+            ('ca-GrQc',0.75,[364,1236,2108],[160,640,1280]),
+            ('soc-Epinions1',0.90,[18,737,1719],[640,2560,5120]),
+            ('web-Google',0.99,[0,2,5],[2560,8192,16384]),
+          ]
+          for ds,rate,roots,batches in configs:
+            for root in roots:
+              for batch in batches:
+                for rep in range(1,6):
+                  out=Path(f'build/heldout/runs/{ds}-r{root}__{batch}__{rep}.json')
+                  with out.open('w') as f: subprocess.run(['build/adaptive_policy_bfs',f'build/heldout/{ds}.txt',str(root),str(rate),str(batch),os.environ['SIMPLE_UPDATE_FRACTION']],stdout=f,check=True)
+                  d=json.load(out.open()); assert d['all_policies_exact']; assert all(p['exact'] for p in d['policies'])
+          PY
+      - name: Regret, oracle match, overhead and crossover
+        run: |
+          python tools/summarize_adaptive_policy.py --input-dir build/heldout/runs --output-dir build/heldout/summary > build/heldout/summary/stdout.json
+          python - <<'PY'
+          import glob,json,statistics
+          d=json.load(open('build/heldout/summary/summary.json')); assert d['all_results_exact']
+          a=[r for r in d['rows'] if r['policy']=='adaptive']; rel=[r['relative_to_regime_best']-1 for r in a]
+          batch_regrets=[]; matches=total=0; overhead=[]
+          for fn in glob.glob('build/heldout/runs/*.json'):
+            x=json.load(open(fn)); ps={p['name']:p for p in x['policies']}; ad=ps['adaptive']['batch_us']; inc=ps['always_incremental']['batch_us']; full=ps['always_full']['batch_us']; simple=ps['simple_threshold']['batch_us']
+            for i,v in enumerate(ad):
+              best=min(inc[i],full[i],simple[i]); batch_regrets.append((v-best)/best); matches += v <= best*1.01; total+=1
+              overhead.append(max(0.0,v-min(inc[i],full[i])))
+          batch_regrets.sort(); p95=batch_regrets[min(len(batch_regrets)-1,int(.95*(len(batch_regrets)-1)))]
+          summary={'all_exact':True,'regimes':len(a),'mean_regret_vs_best_policy':statistics.mean(rel),'p95_batch_regret':p95,'worst_regime_regret':max(rel),'oracle_decision_match_within_1pct':matches/total,'mean_adaptive_excess_us_vs_best_inc_full':statistics.mean(overhead),'crossovers':d['datasets']}
+          print(json.dumps(summary,indent=2)); open('build/heldout/summary/paper-metrics.json','w').write(json.dumps(summary,indent=2)+'\n')
+          assert summary['mean_regret_vs_best_policy'] <= .05, summary
+          assert summary['worst_regime_regret'] <= .25, summary
+          PY
+      - name: Immutable pins
+        if: always()
+        run: |
+          { echo "sha=$(git rev-parse HEAD)"; echo "heldout_roots=ca:364,1236,2108;ep:18,737,1719;web:0,2,5"; echo "heldout_batches=ca:160,640,1280;ep:640,2560,5120;web:2560,8192,16384"; echo "repetitions=5"; } > build/heldout/pins.txt
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: adaptive-policy-heldout-final
+          path: build/heldout/
+          retention-days: 90