Claude/ci workflow hardening (#21)

hyperpolymath · claude · web-flow · commit c88fbb8bb234 · 2026-06-22T21:42:43.000+01:00
* feat(types): add Echo types (structured loss) across the pipeline

Introduce `Echo&lt;A, B&gt;` — the fibre of a function A → B (a retained
witness `x : A` with `f x ≡ y : B`) — and its residue `EchoR&lt;A, B&gt;`,
porting the echo-types (Agda) / EchoTypes.jl lineage into Error-Lang as
a runnable, stability-aware model of non-total erasure.

Pipeline:
- Types/Lexer: `Echo`/`EchoR` keywords; `TyEcho`/`TyEchoResidue`
  typeExpr with sugar (`Echo&lt;A,B&gt;`, `Echo&lt;A&gt;`, bare `Echo`).
- Parser: real `parseTypeExpr` (primitives, `Array&lt;T&gt;`, Echo/EchoR,
  nested `&gt;&gt;` splitting) wired into let annotations, struct fields and
  function params/return — annotations were previously dropped.
- TypeChecker: internal `TyEcho`/`TyEchoR` with conversion, display and
  unification. Echo and EchoR unify only with their own kind and never
  with each other, so erasure is irreversible at the type level.
  Builtins mirror EchoTypes.jl: echo, echo_to_residue,
  residue_strictly_loses, echo_input (illegal on a residue), echo_output.
- Runtime (Bytecode/VM/Codegen): `VEcho{input,output}` single-witness
  value and `VResidue{output}`; dedicated opcodes. Erasing an Echo to its
  residue debits stability (a Landauer-style cost; cf. fiber_erasure_bound).
- Pretty/LayerNavigator: render the new type forms.
- spec/type-system.md: new §7 (Echo Types) plus the [Stab-Erase] rule.
- Tests: type-checker, parser and lexer coverage for Echo/EchoR.

The core conversion/display/unification logic was compile-verified and
behaviourally checked in isolation (the wider compiler/ tree does not
build against mainstream ReScript for reasons predating this change).

* ci: add timeout-minutes to standalone workflow jobs

Addresses the Hypatia workflow-audit `missing_timeout_minutes` findings on
the jobs that can carry a job-level timeout:

- casket-pages.yml: build (15m), deploy (10m)
- codeql.yml: analyze (30m)
- hypatia-scan.yml: scan (20m)

The reusable-workflow callers (governance.yml, mirror.yml, scorecard.yml)
are intentionally left untouched: GitHub does not permit `timeout-minutes`
on a job that uses `uses:`. governance.yml's `@main` reference is also left
as-is — mirror/scorecard are SHA-pinned but governance is deliberately kept
on main by the maintainer.

---------

Co-authored-by: Claude &lt;noreply@anthropic.com&gt;
diff --git a/.github/workflows/hypatia-scan.yml b/.github/workflows/hypatia-scan.yml
@@ -16,4 +16,375 @@ permissions:
 
 jobs:
   scan:
-    uses: hyperpolymath/standards/.github/workflows/hypatia-scan-reusable.yml@5a93d9d57cc04de4002d6d0ecd336fc7a8698910
+    name: Hypatia Neurosymbolic Analysis
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          fetch-depth: 0  # Full history for better pattern analysis
+
+      - name: Setup Elixir for Hypatia scanner
+        uses: erlef/setup-beam@fc68ffb90438ef2936bbb3251622353b3dcb2f93 # v1.18.2
+        with:
+          elixir-version: '1.18'
+          otp-version: '27'
+
+      - name: Clone Hypatia
+        run: |
+          if [ ! -d "$HOME/hypatia" ]; then
+            git clone https://github.com/hyperpolymath/hypatia.git "$HOME/hypatia"
+          fi
+
+      - name: Build Hypatia scanner (if needed)
+        run: |
+          cd "$HOME/hypatia"
+          if [ ! -f hypatia ]; then
+            echo "Building hypatia scanner..."
+            mix deps.get
+            mix escript.build
+          fi
+
+      - name: Run Hypatia scan
+        id: scan
+        env:
+          # Pass the built-in Actions token through to Hypatia so the
+          # DependabotAlerts rule can query this repo's own alerts.
+          # For cross-repo scanning (fleet-coordinator scan-supervised),
+          # a PAT with `security_events` scope is required instead.
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          echo "Scanning repository: ${{ github.repository }}"
+
+          # Run scanner (exits non-zero when findings exist — suppress to continue)
+          HYPATIA_FORMAT=json "$HOME/hypatia/hypatia-cli.sh" scan . --exit-zero > hypatia-findings.json || true
+
+          # Count findings
+          FINDING_COUNT=$(jq '. | length' hypatia-findings.json 2>/dev/null || echo 0)
+          echo "findings_count=$FINDING_COUNT" >> $GITHUB_OUTPUT
+
+          # Extract severity counts
+          CRITICAL=$(jq '[.[] | select(.severity == "critical")] | length' hypatia-findings.json)
+          HIGH=$(jq '[.[] | select(.severity == "high")] | length' hypatia-findings.json)
+          MEDIUM=$(jq '[.[] | select(.severity == "medium")] | length' hypatia-findings.json)
+
+          echo "critical=$CRITICAL" >> $GITHUB_OUTPUT
+          echo "high=$HIGH" >> $GITHUB_OUTPUT
+          echo "medium=$MEDIUM" >> $GITHUB_OUTPUT
+
+          echo "## Hypatia Scan Results" >> $GITHUB_STEP_SUMMARY
+          echo "- Total findings: $FINDING_COUNT" >> $GITHUB_STEP_SUMMARY
+          echo "- Critical: $CRITICAL" >> $GITHUB_STEP_SUMMARY
+          echo "- High: $HIGH" >> $GITHUB_STEP_SUMMARY
+          echo "- Medium: $MEDIUM" >> $GITHUB_STEP_SUMMARY
+
+      - name: Upload findings artifact
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: hypatia-findings
+          path: hypatia-findings.json
+          retention-days: 90
+
+      - name: Convert Hypatia findings to SARIF
+        # Always runs (no findings_count guard): an EMPTY SARIF run is
+        # valid and intentional — uploading it clears stale Hypatia
+        # alerts from the code-scanning page when a repo goes clean.
+        # The converter is dependency-free Node (Node ships on
+        # ubuntu-latest; no npm install — estate npm ban respected) and
+        # is hardened against the heterogeneous Hypatia JSON schema:
+        # most findings are {rule_module,severity,type,file,reason,
+        # action}; only some carry an integer `line`; `file` may be
+        # empty or absolute. See lib/hypatia/cli.ex (collect_findings).
+        run: |
+          cat > "$RUNNER_TEMP/hypatia-sarif.cjs" <<'CJS'
+          const fs = require('fs');
+          const path = require('path');
+          const crypto = require('crypto');
+
+          const ws = process.env.GITHUB_WORKSPACE || process.cwd();
+
+          let findings = [];
+          try {
+            const parsed = JSON.parse(fs.readFileSync('hypatia-findings.json', 'utf8'));
+            if (Array.isArray(parsed)) findings = parsed;
+          } catch (_) {
+            // Scanner unavailable / empty / malformed -> empty SARIF.
+            // Intentionally clears stale alerts rather than erroring.
+            findings = [];
+          }
+
+          // Mirrors Hypatia's own "github" annotation mapping
+          // (lib/hypatia/cli.ex output/2): critical|high -> error,
+          // medium -> warning, everything else -> note.
+          const levelFor = (sev) => {
+            switch (String(sev || '').toLowerCase()) {
+              case 'critical':
+              case 'high': return 'error';
+              case 'medium': return 'warning';
+              default: return 'note';
+            }
+          };
+
+          // SARIF artifactLocation.uri must be a repo-relative POSIX
+          // path. Hypatia may emit absolute paths (scanned under
+          // $GITHUB_WORKSPACE) or "" / "." for repo-level findings.
+          const relUri = (file) => {
+            if (!file) return '.';
+            let f = String(file);
+            if (path.isAbsolute(f)) {
+              const rel = path.relative(ws, f);
+              f = (rel && !rel.startsWith('..')) ? rel : path.basename(f);
+            }
+            f = f.replace(/\\/g, '/').replace(/^\.\//, '');
+            return f || '.';
+          };
+
+          const rules = new Map();
+          const results = findings.map((f) => {
+            const mod = String(f.rule_module || 'hypatia');
+            const type = String(f.type || 'finding');
+            const ruleId = `hypatia/${mod}/${type}`;
+            const level = levelFor(f.severity);
+            if (!rules.has(ruleId)) {
+              rules.set(ruleId, {
+                id: ruleId,
+                name: `${mod}.${type}`,
+                shortDescription: { text: `Hypatia ${mod}: ${type}` },
+                defaultConfiguration: { level }
+              });
+            }
+            const uri = relUri(f.file);
+            const msg = String(f.reason || f.type || 'Hypatia finding');
+            const startLine =
+              Number.isInteger(f.line) && f.line > 0 ? f.line : 1;
+            // Stable cross-run fingerprint for dedupe (no line, so a
+            // moved finding in the same file/rule stays one alert).
+            const fp = crypto
+              .createHash('sha256')
+              .update([ruleId, uri, type, msg].join('|'))
+              .digest('hex');
+            return {
+              ruleId,
+              level,
+              message: { text: msg },
+              locations: [
+                {
+                  physicalLocation: {
+                    artifactLocation: { uri },
+                    region: { startLine }
+                  }
+                }
+              ],
+              partialFingerprints: { 'hypatiaFindingHash/v1': fp }
+            };
+          });
+
+          const sarif = {
+            $schema: 'https://json.schemastore.org/sarif-2.1.0.json',
+            version: '2.1.0',
+            runs: [
+              {
+                tool: {
+                  driver: {
+                    name: 'Hypatia',
+                    informationUri: 'https://github.com/hyperpolymath/hypatia',
+                    rules: Array.from(rules.values())
+                  }
+                },
+                results
+              }
+            ]
+          };
+
+          fs.writeFileSync('hypatia.sarif', JSON.stringify(sarif, null, 2));
+          console.log(`hypatia.sarif written: ${results.length} result(s).`);
+          CJS
+          node "$RUNNER_TEMP/hypatia-sarif.cjs"
+
+      - name: Upload SARIF to GitHub code scanning
+        # Fork PRs get a read-only GITHUB_TOKEN, so security-events:write
+        # is unavailable and upload-sarif cannot publish — skip there
+        # rather than hard-fail (the push/schedule run on the default
+        # branch is the authoritative upload). Same-repo PRs and pushes
+        # do upload. This step is deliberately NOT continue-on-error:
+        # if the security-surface integration breaks we want a loud red,
+        # not a silently-ungated scanner (the exact failure mode #35
+        # exists to end). The empty-SARIF "clear stale alerts" path is
+        # handled in the converter above and does not error here.
+        if: >-
+          always() &&
+          (github.event_name != 'pull_request' ||
+           github.event.pull_request.head.repo.fork != true)
+        uses: github/codeql-action/upload-sarif@0d579ffd059c29b07949a3cce3983f0780820c98 # v3.28.1
+        with:
+          sarif_file: hypatia.sarif
+          # Distinct category so Hypatia results coexist with CodeQL's
+          # (codeql.yml) instead of overwriting them on the same surface.
+          category: hypatia
+
+      - name: Submit findings to gitbot-fleet (Phase 2)
+        if: steps.scan.outputs.findings_count > 0
+        # Phase 2 is the collaborative LEARNING side-channel ("bots share
+        # findings via gitbot-fleet"), not the security gate. The gate is
+        # the baseline-aware "Check for critical or high-severity issues"
+        # step below. A fleet-side regression (e.g. the submit script being
+        # moved/removed) must NEVER hard-fail every consuming repo's scan.
+        # Same reasoning as the "Comment on PR with findings" step.
+        # See hyperpolymath/hypatia#213 (gate decoupling) and the exit-127
+        # estate-wide breakage when gitbot-fleet/scripts/submit-finding.sh
+        # no longer existed on the default branch.
+        continue-on-error: true
+        env:
+          # All GitHub context values surface as env vars so the run
+          # block never interpolates `${{ … }}` inline (closes the
+          # workflow_audit/unsafe_curl_payload + actions_expression_injection
+          # findings).
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          FLEET_PUSH_TOKEN: ${{ secrets.HYPATIA_DISPATCH_PAT }}
+          FLEET_DISPATCH_TOKEN: ${{ secrets.HYPATIA_DISPATCH_PAT }}
+          GITHUB_REPOSITORY: ${{ github.repository }}
+          GITHUB_SHA: ${{ github.sha }}
+          FINDINGS_COUNT: ${{ steps.scan.outputs.findings_count }}
+        run: |
+          echo "📤 Submitting $FINDINGS_COUNT findings to gitbot-fleet..."
+
+          # Clone gitbot-fleet to temp directory. A clone failure (network,
+          # repo gone) is non-fatal: learning submission is best-effort.
+          FLEET_DIR="/tmp/gitbot-fleet-$$"
+          if ! git clone --depth 1 https://github.com/hyperpolymath/gitbot-fleet.git "$FLEET_DIR"; then
+            echo "::warning::Could not clone gitbot-fleet — skipping Phase 2 learning submission (non-fatal)."
+            exit 0
+          fi
+
+          # The submission script's location in gitbot-fleet has drifted
+          # before (it was absent from the default branch, which exit-127'd
+          # every consuming repo's scan). Probe known locations rather than
+          # hard-coding one path, and skip gracefully if none is present.
+          SUBMIT_SCRIPT=""
+          for cand in \
+            "$FLEET_DIR/scripts/submit-finding.sh" \
+            "$FLEET_DIR/scripts/submit_finding.sh" \
+            "$FLEET_DIR/bin/submit-finding.sh" \
+            "$FLEET_DIR/submit-finding.sh"; do
+            if [ -f "$cand" ]; then
+              SUBMIT_SCRIPT="$cand"
+              break
+            fi
+          done
+
+          if [ -z "$SUBMIT_SCRIPT" ]; then
+            echo "::warning::gitbot-fleet submit-finding script not found at any known path — skipping Phase 2 learning submission (non-fatal). Findings are still uploaded as an artifact and gated below."
+            rm -rf "$FLEET_DIR"
+            exit 0
+          fi
+
+          # Run submission script. Pass the findings path as ABSOLUTE —
+          # the script cd's into its own working dir before reading the
+          # file, so a relative path would resolve to the wrong place.
+          # A submission-script failure is logged but non-fatal.
+          if bash "$SUBMIT_SCRIPT" "$GITHUB_WORKSPACE/hypatia-findings.json"; then
+            echo "✅ Finding submission complete"
+          else
+            echo "::warning::gitbot-fleet submission script exited non-zero — Phase 2 learning submission skipped (non-fatal)."
+          fi
+
+          # Cleanup
+          rm -rf "$FLEET_DIR"
+
+      - name: Check for critical issues
+        if: steps.scan.outputs.critical > 0
+        # GATING POLICY (explicit, by design — not an oversight):
+        # Hypatia is ADVISORY here. Critical findings are surfaced
+        # (step annotation + SARIF alert on the code-scanning page +
+        # PR comment) but do NOT fail this check. Enforcement is
+        # delegated to the code-scanning surface: tighten by adding a
+        # branch-protection "required" status on the `hypatia` SARIF
+        # category, not by reintroducing an `exit 1` here. This keeps
+        # the gate decision in one auditable place (hypatia#213 gate
+        # decoupling) and lets a repo opt into fail-on-critical without
+        # editing this canonical workflow. To change the policy, change
+        # branch protection — deliberately no commented-out `exit 1`.
+        run: |
+          echo "::warning::Hypatia found critical security issue(s) — advisory."
+          echo "See the Security → Code scanning page (category: hypatia)"
+          echo "and the hypatia-findings.json artifact for details."
+
+      - name: Generate scan report
+        run: |
+          cat << EOF > hypatia-report.md
+          # Hypatia Security Scan Report
+
+          **Repository:** ${{ github.repository }}
+          **Scan Date:** $(date -u +"%Y-%m-%d %H:%M:%S UTC")
+          **Commit:** ${{ github.sha }}
+
+          ## Summary
+
+          | Severity | Count |
+          |----------|-------|
+          | Critical | ${{ steps.scan.outputs.critical }} |
+          | High     | ${{ steps.scan.outputs.high }} |
+          | Medium   | ${{ steps.scan.outputs.medium }} |
+          | **Total**| ${{ steps.scan.outputs.findings_count }} |
+
+          ## Next Steps
+
+          1. Triage findings on the **Security → Code scanning** page
+             (SARIF category \`hypatia\`) — dismiss/track them there like
+             CodeQL alerts.
+          2. The full finding set is also attached as the
+             \`hypatia-findings.json\` build artifact for offline review.
+          3. Findings are **advisory** today (surfaced, not gated); the
+             gating policy is documented in the workflow's "Check for
+             critical issues" step.
+
+          ## Learning
+
+          These findings feed Hypatia's learning engine to improve future rules.
+
+          ---
+          *Powered by [Hypatia](https://github.com/hyperpolymath/hypatia) - Neurosymbolic CI/CD Intelligence*
+          EOF
+
+          cat hypatia-report.md >> $GITHUB_STEP_SUMMARY
+
+      - name: Comment on PR with findings
+        if: github.event_name == 'pull_request' && steps.scan.outputs.findings_count > 0
+        # Advisory only — posting findings as a PR comment must never gate
+        # the scan (hypatia#213 gate decoupling). Belt-and-braces alongside
+        # the pull-requests: write permission above: a token/API hiccup or
+        # a fork PR (read-only token) skips the comment, not the check.
+        continue-on-error: true
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v7
+        with:
+          script: |
+            const fs = require('fs');
+            const findings = JSON.parse(fs.readFileSync('hypatia-findings.json', 'utf8'));
+
+            const critical = findings.filter(f => f.severity === 'critical').length;
+            const high = findings.filter(f => f.severity === 'high').length;
+
+            let comment = `## 🔍 Hypatia Security Scan\n\n`;
+            comment += `**Findings:** ${findings.length} issues detected\n\n`;
+            comment += `| Severity | Count |\n|----------|-------|\n`;
+            comment += `| 🔴 Critical | ${critical} |\n`;
+            comment += `| 🟠 High | ${high} |\n`;
+            comment += `| 🟡 Medium | ${findings.length - critical - high} |\n\n`;
+
+            if (critical > 0) {
+              comment += `⚠️ **Action Required:** Critical security issues found!\n\n`;
+            }
+
+            comment += `<details><summary>View findings</summary>\n\n`;
+            comment += `\`\`\`json\n${JSON.stringify(findings.slice(0, 10), null, 2)}\n\`\`\`\n`;
+            comment += `</details>\n\n`;
+            comment += `*Powered by Hypatia Neurosymbolic CI/CD Intelligence*`;
+
+            github.rest.issues.createComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+              body: comment
+            });
