contract.yml

# CI for the programir contract (AUTHORITY.md: fixtures under law).
#
# Modeled on lm15-contract/.github/workflows/contract.yml. Every `run:`
# command below works verbatim from the repo root on a local checkout —
# the workflow adds nothing you cannot reproduce with a plain shell.
#
# Jobs:
#   gates          — provenance gate, harness mutation self-test, reference
#                    interpreter self-check.
#   reference-shim — full corpus against the grade-1 reference shim.
#   go-shim        — full corpus against programir-go, IF the repo variable
#                    PROGRAMIR_GO_REF is set (see the job comment; the go
#                    port lives in a separate repo not yet on GitHub, so
#                    this job self-skips with a notice until then).
#   l8-guard       — the corpus rule L8 (AUTHORITY.md): fixture changes and
#                    spec changes never share a commit.
#
# SANDBOX TODO (honest limitation, see tools/sandbox_note.md and the
# harness/check.py docstring): PROTOCOL.md requires shims to run with the
# network blocked; that enforcement (lm15's `unshare -rn` wrapper) is NOT
# yet transplanted, and GitHub-hosted runners give shims ambient network
# access. A green run here is therefore NOT sufficient to ratify a
# conformance claim until the no-network sandbox lands (check.py prints
# the same warning). Grade-1 ops are pure by construction, so the exposure
# is a shim cheating by phoning out — which is exactly what the sandbox
# exists to make impossible rather than merely forbidden.

name: contract

on:
  push:
  pull_request:

jobs:
  # ------------------------------------------------------------------
  # Gate battery. Locally:  (from repo root)
  #   python3 tools/check_provenance.py
  #   python3 harness/selftest.py
  #   python3 reference/selfcheck_interp.py
  # ------------------------------------------------------------------
  gates:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - name: Enforce fixture provenance (AUTHORITY.md — no fixture lands without it)
        run: python3 tools/check_provenance.py
      - name: Mutation self-test (the comparator must catch every injected mutation)
        run: python3 harness/selftest.py
      - name: Reference interpreter self-check (SEM rulings + legacy 13/14/15 replay)
        run: python3 reference/selfcheck_interp.py

  # ------------------------------------------------------------------
  # Full corpus against the reference shim. Locally:
  #   python3 harness/check.py --shim reference
  # Reports regenerate into harness/reports/ (gitignored).
  # ------------------------------------------------------------------
  reference-shim:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - name: Run corpus against the reference shim
        run: python3 harness/check.py --shim reference

  # ------------------------------------------------------------------
  # Full corpus against the go port. harness/shims.json registers the go
  # shim with cwd ../programir-go, i.e. a SIBLING checkout of the contract
  # repo — which is how it works locally. programir-go is a separate repo
  # that is not yet on GitHub, so CI cannot check it out unconditionally.
  #
  # Wiring, once programir-go is pushed to GitHub: set a repository
  # variable (Settings → Secrets and variables → Actions → Variables)
  #
  #   PROGRAMIR_GO_REF = owner/programir-go          (default branch)
  #   PROGRAMIR_GO_REF = owner/programir-go@<ref>    (branch / tag / SHA —
  #        e.g. pin the SHA recorded in IMPLEMENTATIONS.md's registry row)
  #
  # Until the variable is set, the job emits a ::notice:: and succeeds
  # without running anything — a skip, honestly labeled, never a pass
  # (the same honesty rule the harness applies to capability skips).
  # If programir-go is private, actions/checkout will additionally need a
  # `token:` with read access to it; the default GITHUB_TOKEN only reads
  # this repo.
  #
  # Locally (with programir-go cloned as a sibling):
  #   python3 harness/check.py --shim go
  # ------------------------------------------------------------------
  go-shim:
    runs-on: ubuntu-latest
    steps:
      - name: Resolve programir-go source (skip with notice if unset)
        id: gate
        env:
          RAW: ${{ vars.PROGRAMIR_GO_REF }}
        run: |
          if [ -z "$RAW" ]; then
            echo "::notice title=go-shim skipped::PROGRAMIR_GO_REF repo variable is unset — programir-go is a separate repo not yet on GitHub, so its conformance run is skipped (not passed). Set PROGRAMIR_GO_REF=owner/programir-go[@ref] once it exists."
            echo "available=false" >> "$GITHUB_OUTPUT"
          else
            echo "available=true" >> "$GITHUB_OUTPUT"
            echo "repo=${RAW%%@*}" >> "$GITHUB_OUTPUT"
            if [ "${RAW#*@}" != "$RAW" ]; then
              echo "ref=${RAW#*@}" >> "$GITHUB_OUTPUT"
            else
              echo "ref=" >> "$GITHUB_OUTPUT"
            fi
          fi
      # Sibling layout under $GITHUB_WORKSPACE mirrors the local layout
      # that harness/shims.json's `cwd: ../programir-go` expects.
      - uses: actions/checkout@v4
        if: steps.gate.outputs.available == 'true'
        with:
          path: programir-contract
      - uses: actions/checkout@v4
        if: steps.gate.outputs.available == 'true'
        with:
          repository: ${{ steps.gate.outputs.repo }}
          ref: ${{ steps.gate.outputs.ref }}
          path: programir-go
      - uses: actions/setup-go@v5
        if: steps.gate.outputs.available == 'true'
        with:
          go-version: "1.26"
      - uses: actions/setup-python@v5
        if: steps.gate.outputs.available == 'true'
        with:
          python-version: "3.12"
      - name: Run corpus against the go shim
        if: steps.gate.outputs.available == 'true'
        working-directory: programir-contract
        run: python3 harness/check.py --shim go

  # ------------------------------------------------------------------
  # Corpus rule L8 (AUTHORITY.md): "Fixture regeneration happens only in
  # dedicated commits containing zero spec changes." The guard is
  # per-COMMIT over the event's range, not over the aggregate diff —
  # a single commit touching both spec/*.md and a fixture violates L8
  # even when the PR's net diff is clean on one side.
  #
  # "Fixture" means `cases/**/*.json` — exactly the files that carry
  # provenance (harness/CASES-FORMAT.md, tools/check_provenance.py) —
  # NOT all of cases/**: cases/README.md is family-plan prose, and the
  # ratified seed commit legitimately touched it alongside spec/.
  #
  # Range: pull_request → base..head; push → event.before..sha, falling
  # back to the head commit alone when `before` is unknowable (branch
  # creation) or unfetchable (history rewritten by a force-push).
  # Merge commits diff empty under `git diff-tree -r` without -m and are
  # effectively skipped; their constituent commits are checked directly.
  # `--root` makes a root commit diff against the empty tree instead of
  # silently diffing as nothing (a first-commit PR must not slip through).
  #
  # Locally, over any range:
  #   for c in $(git rev-list BASE..HEAD); do
  #     git diff-tree --root --no-commit-id --name-only -r "$c"  # eyeball,
  #   done                                            # or reuse the loop below
  # ------------------------------------------------------------------
  l8-guard:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0 # the guard walks commit-by-commit; it needs history
      - name: "L8: no commit touches both spec/*.md and cases/**/*.json"
        env:
          EVENT: ${{ github.event_name }}
          BASE_SHA: ${{ github.event.pull_request.base.sha }}
          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
          BEFORE: ${{ github.event.before }}
          SHA: ${{ github.sha }}
        run: |
          set -eu
          if [ "$EVENT" = "pull_request" ]; then
            COMMITS=$(git rev-list "$BASE_SHA..$HEAD_SHA")
          elif [ -n "$BEFORE" ] \
               && [ "$BEFORE" != "0000000000000000000000000000000000000000" ] \
               && git cat-file -e "$BEFORE^{commit}" 2>/dev/null; then
            COMMITS=$(git rev-list "$BEFORE..$SHA")
          else
            echo "::warning title=L8 guard::push range start unknown (branch creation or force-push); checking the head commit only."
            COMMITS="$SHA"
          fi
          bad=0
          for c in $COMMITS; do
            files=$(git diff-tree --root --no-commit-id --name-only -r "$c")
            spec=$(printf '%s\n' "$files" | grep -c '^spec/[^/]*\.md$' || true)
            cases=$(printf '%s\n' "$files" | grep -c '^cases/.*\.json$' || true)
            if [ "$spec" -gt 0 ] && [ "$cases" -gt 0 ]; then
              echo "::error title=L8 violation::commit $c touches both spec/*.md and cases/**/*.json — AUTHORITY.md: fixture regeneration happens only in dedicated commits containing zero spec changes. Split the commit."
              git show --no-patch --format='  %h %s' "$c"
              printf '%s\n' "$files" | grep -E '^(spec/[^/]*\.md$|cases/.*\.json$)' | sed 's/^/    /'
              bad=1
            fi
          done
          if [ "$bad" -eq 0 ]; then
            echo "L8 guard: OK ($(printf '%s\n' $COMMITS | grep -c . || true) commit(s) checked)"
          fi
          exit "$bad"