feat(verify): tiered data verification layer (Tier 0 offline scoring)

.github/workflows/request-engine-pr-validation.yml

@@ -17,6 +17,7 @@ on:
       - "site/package.json"
       - "site/package-lock.json"
       - "app/validate.py"
+      - "app/verify/**"
   workflow_dispatch:
     inputs:
       pr_number:

.github/workflows/verify-network.yml

@@ -0,0 +1,116 @@
+name: verify-network
+
+# Network verification tiers (source-URL liveness + external cross-reference) and
+# verified promotion. NEVER runs on pull_request — these tiers hit external sites,
+# are rate-limited, and must not gate a merge. Scheduled + manual only. Promotions
+# are written on a branch and opened as a PR for human review; the job hard-guards
+# that nothing but `verified` flags and the ledger changed.
+
+on:
+  workflow_dispatch:
+    inputs:
+      apply:
+        description: "Flip verified->true and open a PR (otherwise dry-run only)"
+        type: boolean
+        default: false
+      max_urls:
+        description: "Frontier records to URL-check"
+        default: "2000"
+      max_crossref:
+        description: "Yellow/red records to cross-reference"
+        default: "500"
+  schedule:
+    - cron: "0 4 * * 1"  # Mondays 04:00 UTC
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  verify-network:
+    runs-on: ubuntu-latest
+    env:
+      PYTHONIOENCODING: utf-8
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      # Resumable caches (URL + crossref). Recomputable, so a miss is harmless.
+      - name: Restore verify caches
+        uses: actions/cache@v4
+        with:
+          path: data/_verify/state
+          key: verify-state-${{ github.run_id }}
+          restore-keys: verify-state-
+
+      - name: Tier 0 score (writes scores cache)
+        run: python -m app.verify score
+
+      - name: Tier 1 source-URL liveness
+        run: python -m app.verify check-urls --max ${{ github.event.inputs.max_urls || '2000' }}
+
+      - name: Tier 2 external cross-reference
+        run: python -m app.verify crossref --max ${{ github.event.inputs.max_crossref || '500' }}
+
+      - name: Tier 3 promote (dry-run)
+        run: python -m app.verify promote
+
+      - name: Tier 3 promote (apply)
+        if: ${{ github.event.inputs.apply == 'true' }}
+        run: python -m app.verify promote --apply
+
+      - name: Structural validator self-check
+        if: ${{ github.event.inputs.apply == 'true' }}
+        run: python -m app.validate
+
+      # Guard: the only tracked changes may be `verified` toggles in data/**.json
+      # plus the promotion ledger. Anything else fails the run loudly.
+      - name: Guard diff scope
+        if: ${{ github.event.inputs.apply == 'true' }}
+        run: |
+          python - <<'PY'
+          import subprocess, sys
+          out = subprocess.run(["git", "diff", "--unified=0", "--", "data/"],
+                               capture_output=True, text=True).stdout
+          bad = []
+          for line in out.splitlines():
+              if line.startswith(("+++", "---", "@@", "diff ", "index ")):
+                  continue
+              if line.startswith(("+", "-")) and line[1:].strip():
+                  body = line[1:].strip().rstrip(",")
+                  if body not in ('"verified": true', '"verified": false'):
+                      bad.append(line)
+          if bad:
+              print("Unexpected non-verified changes:")
+              print("\n".join(bad[:50]))
+              sys.exit(1)
+          print("diff scope OK: only verified toggles")
+          PY
+
+      - name: Open promotion PR
+        if: ${{ github.event.inputs.apply == 'true' }}
+        env:
+          GH_TOKEN: ${{ secrets.TECHAPI_TOKEN || secrets.GITHUB_TOKEN }}
+        run: |
+          set -e
+          if git diff --quiet -- data/; then
+            echo "no promotions to commit"; exit 0
+          fi
+          branch="verify/promote-${{ github.run_id }}"
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git checkout -b "$branch"
+          git add data/
+          git commit -m "data(verify): promote records to verified via cross-reference
+
+          Auto-promotions from the verification layer (green+live-T1 or crossref-confirm).
+          Each flip is verified:false->true only; see data/_verify/ledger.jsonl. Refs #1"
+          git push origin "$branch"
+          gh pr create --base main --head "$branch" \
+            --title "data(verify): verified promotions ($(date -u +%Y-%m-%d))" \
+            --body "Automated verified promotions from \`app.verify promote\`. Each change flips only the \`verified\` flag; structural validator passed and diff scope guarded. Review before merge. Refs #1"

.github/workflows/verify-report.yml

@@ -0,0 +1,103 @@
+name: verify-report
+
+# Run the Tier 0 offline data *verification* (existence/trust scoring) on a PR and
+# let TechEngineBot post the band analysis as a PR comment. The bot owns the
+# analysis surface: this workflow only computes the report and hands it to the bot,
+# which authors the comment via its own PAT (TECHENGINEBOT_TOKEN). It never gates a
+# merge.
+#
+# Dormant unless a bot/automation token is configured. Restricted to same-repo
+# branch PRs so fork PRs never see the token. The structural gate stays in
+# validate-data.yml; this is purely informational.
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review]
+    paths:
+      - "data/**"
+      - "app/validate.py"
+      - "app/verify/**"
+
+permissions:
+  contents: read
+  pull-requests: write
+
+concurrency:
+  group: verify-report-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  verify-report:
+    runs-on: ubuntu-latest
+    if: github.event.pull_request.head.repo.full_name == github.repository
+    env:
+      PYTHONIOENCODING: utf-8
+      # Prefer TechEngineBot's PAT so the analysis comment is authored by the bot
+      # (TECHENGINEBOT_TOKEN, Issues/PR write on both repos). Fall back to
+      # ENGINE_TOKEN only so the workflow still runs if the bot token is absent.
+      BOT_TOKEN: ${{ secrets.TECHENGINEBOT_TOKEN || secrets.ENGINE_TOKEN }}
+    steps:
+      - name: Dormant when no bot token is configured
+        if: env.BOT_TOKEN == ''
+        run: echo "::warning::No TECHENGINEBOT_TOKEN/ENGINE_TOKEN — TechEngineBot verify comment skipped."
+
+      - uses: actions/checkout@v4
+        if: env.BOT_TOKEN != ''
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        if: env.BOT_TOKEN != ''
+        with:
+          python-version: "3.12"
+
+      - name: Tier 0 verification (changed + full baseline)
+        if: env.BOT_TOKEN != ''
+        id: verify
+        run: |
+          git fetch origin main --depth=1 || true
+          {
+            echo 'report<<VERIFY_EOF'
+            echo "### Changed records in this PR"
+            python -m app.verify score --changed --no-cache
+            echo ""
+            echo "### Full-dataset baseline"
+            python -m app.verify score --no-cache
+            echo VERIFY_EOF
+          } >> "$GITHUB_OUTPUT"
+
+      - name: TechEngineBot posts the verification analysis
+        if: env.BOT_TOKEN != ''
+        uses: actions/github-script@v7
+        env:
+          REPORT: ${{ steps.verify.outputs.report }}
+        with:
+          github-token: ${{ secrets.TECHENGINEBOT_TOKEN || secrets.ENGINE_TOKEN }}
+          script: |
+            const marker = '<!-- techengine-verify-report -->';
+            const report = (process.env.REPORT || '').trim() || '(no output)';
+            const body = [
+              marker,
+              '## 🔎 Data verification — Tier 0 (offline existence/trust)',
+              '',
+              'Scored by `app.verify`; posted by **TechEngineBot**. Informational only —',
+              'the structural gate (`app.validate`) is separate and authoritative for merge.',
+              '',
+              '```text',
+              report,
+              '```',
+              '',
+              '<sub>green = authoritative source + complete + consistent · '
+                + 'yellow = plausible, needs confirmation · red = sparse/weak source or a hard contradiction. '
+                + 'Promotion to `verified` runs in the scheduled `verify-network` workflow.</sub>',
+            ].join('\n');
+            const { owner, repo } = context.repo;
+            const issue_number = context.payload.pull_request.number;
+            const comments = await github.paginate(github.rest.issues.listComments, {
+              owner, repo, issue_number, per_page: 100,
+            });
+            const existing = comments.find((c) => c.body && c.body.includes(marker));
+            if (existing) {
+              await github.rest.issues.updateComment({ owner, repo, comment_id: existing.id, body });
+            } else {
+              await github.rest.issues.createComment({ owner, repo, issue_number, body });
+            }

.gitignore

@@ -31,6 +31,10 @@ env/
 # Note: data/_staging/ (raw collected candidate pool) is intentionally tracked —
 # comprehensive data collection is a purpose of this repo.
 
+# Verification layer caches: full Tier 0 scores + network caches are cheap to
+# recompute. Only data/_verify/ledger.jsonl (the promotion audit trail) is tracked.
+data/_verify/state/
+
 # Testing / coverage
 .pytest_cache/
 .coverage

app/verify/__init__.py

@@ -0,0 +1,18 @@
+"""TechAPI data *verification* layer (§ existence/trust, sits above structural validation).
+
+``app.validate`` answers "is this record well-formed?". ``app.verify`` answers
+"does this record describe a real, actually-existing device/part — confidently
+enough to mark it ``verified``?".
+
+It is a separate, additive layer: the structural validator (``app/validate.py``)
+stays the fast CI gate and is never rewritten. Verification is tiered:
+
+* Tier 0 — offline deterministic plausibility score over the whole dataset
+  (``offline``/``signals``/``hosts``); bands records green/yellow/red.
+* Tier 1 — ``source_urls`` HTTP liveness (``http_check``).
+* Tier 2 — external cross-reference under an exact-heading rule (``crossref``).
+* Tier 3 — hybrid escalation + safe ``verified:true`` write-back (``promote``).
+
+Decisions are recorded append-only in ``data/_verify/ledger.jsonl`` so runs are
+incremental and resumable.
+"""

app/verify/__main__.py

@@ -0,0 +1,8 @@
+"""``python -m app.verify`` entry point."""
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())