Skip to content
Open
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
9 changes: 6 additions & 3 deletions .github/workflows/proofs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -16,8 +16,9 @@
# Why: this repository has no Guix manifest and no proof container yet;
# the hosted runner has no Guix. The Debian package is an exact,
# signature-checked pin.
# Closes: when a Guix manifest (or the repo's container) provides Agda and
# this job installs from it.
# Closes: PN-7 (docs/status/PROOF-NEEDS.adoc): when the planned
# digest-pinned Agda image from the shared prover-images repo
# (not yet created) replaces this install. Owner ruling 2026-11-18.
on:
push:
branches: [main]
Expand All @@ -29,7 +30,7 @@
name: Core proofs and expected rejections
runs-on: ubuntu-latest
timeout-minutes: 15
container: debian:trixie-slim

Check warning on line 33 in .github/workflows/proofs.yml

View workflow job for this annotation

GitHub Actions / Hypatia neurosymbolic scan

[hypatia] workflow .github/workflows/proofs.yml:33 pins container `debian:trixie-slim` by tag — tag is mutable; pin by sha256 digest instead
steps:
- name: Install the pinned prover
run: |
Expand Down Expand Up @@ -74,7 +75,9 @@
# Tool: Lean 4.35.0, the upstream release archive, checked against the
# SHA256 below; the version is asserted against lean-toolchain.
# Why: no Guix manifest or proof container provides Lean here yet.
# Closes: when a Guix manifest (or the repo's container) provides Lean.
# Closes: PN-7 (docs/status/PROOF-NEEDS.adoc): when the planned
# digest-pinned Lean image from the shared prover-images repo
# (not yet created) replaces this install. Owner ruling 2026-11-18.
lean-leg:
name: Lean recheck leg
runs-on: ubuntu-latest
Expand Down
259 changes: 259 additions & 0 deletions docs/handoff/prover-images/README.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,259 @@
// SPDX-License-Identifier: CC-BY-SA-4.0
= prover-images (DRAFT handoff)
:revdate: 2026-11-18

[WARNING]
====
*DRAFT and UNTESTED.*

* The images have never been built: the authoring container could not reach the Debian mirrors.
* The `snapshot.debian.org` timestamp (`SNAPSHOT_TS` in `agda/Containerfile`) is unverified.
* The `actions/attest` version is unconfirmed.
* Two hardening changes are unverified: the Agda image reaches `snapshot.debian.org` over https using a CA bundle copied from a first build stage (no `http://` URI remains), and both images end as the non-root user `prover` (uid 1001). Neither has been built, and whether a job `container:` still needs `options: --user root` is untested.
* The name `prover-images` has not been checked against `gv-clade-index`.
* The licence (SPDX lines) is a placeholder for the owner to decide.
* This directory moves to `hyperpolymath/prover-images` once that repository exists, and is then deleted here (PN-7 in `docs/status/PROOF-NEEDS.adoc`).
* The draft CI files are carried as listings at the end of this file, not as YAML files, so nothing in resource-algebra treats them as live config. In the target repository they become `.github/workflows/build.yml` and `.github/dependabot.yml`.
====

*Status: draft, untested.* Written by an agent from resource-algebra PN-7 for
the owner to adopt when this repository is created. Nothing here has been built
or published (see "Validation so far"). The name `prover-images` is provisional
and has not been checked against `gv-clade-index`.

== Purpose

Digest-pinned container images for proof checkers, so that a proof receipt can
name the image its checker ran in (`NAME[:TAG]@sha256:<64 hex>`), as
PROOF-POLICY §8.2 (standards#1625) requires for PWG-1. First consumer:
resource-algebra (Agda 2.6.4.3, Lean 4.35.0).

== IS / IS-NOT (draft)

IS:: digest-pinned prover images for PWG-1 receipts, with the checker baked in,
a smoke test per image, and published provenance.
IS-NOT:: a place for proofs, theorems or policy. Policy stays in `standards`;
proofs stay in the repositories that own them.

== Layout

* `agda/Containerfile`: `debian:trixie-slim@sha256:a72b4433…` (digest checked
against the Docker Hub API on 2026-11-18 and pulled by digest locally), Debian
`agda-bin 2.6.4.3-1+b2` from a snapshot.debian.org timestamp.
* `lean/Containerfile`: same base, the upstream Lean 4.35.0 archive checked
against the SHA256 in resource-algebra's `proofs.yml`.
* `.github/workflows/build.yml` (listing below): build, smoke test, push to
`ghcr.io/hyperpolymath/prover-images/{agda,lean}`, print the digest in the job
summary, attest provenance. Pushes only off `pull_request`.
* `.github/dependabot.yml` (listing below): weekly base-digest and action bumps.

== How a consumer pins a digest

Read the `image:` line in the build job's summary (or
`docker buildx imagetools inspect ghcr.io/hyperpolymath/prover-images/agda:sha-<commit>`)
and paste `ghcr.io/hyperpolymath/prover-images/agda@sha256:<digest>`. Never pin
a tag alone. Confirm with `gh attestation verify oci://…@sha256:<digest>
--repo hyperpolymath/prover-images`.

== The resource-algebra diff this will need

In `.github/workflows/proofs.yml`, keep every gate step and change only:

[source,diff]
----
proofs:
- container: debian:trixie-slim
+ container:
+ image: ghcr.io/hyperpolymath/prover-images/agda@sha256:<filled-in-after-publish>
steps:
- - name: Install the pinned prover
- run: |
- apt-get update
- apt-get install --no-install-recommends -y ca-certificates git agda-bin=2.6.4.3-1+b2
- uses: actions/checkout@…
lean-leg:
- runs-on: ubuntu-latest
+ runs-on: ubuntu-latest
+ container:
+ image: ghcr.io/hyperpolymath/prover-images/lean@sha256:<filled-in-after-publish>
steps:
- - name: Install the pinned Lean
- … # curl + sha256sum + tar + GITHUB_PATH
----

Also: add `- image: \`ghcr.io/…@sha256:…\`` to the Agda, Lean and M-2 receipt
summaries; keep the version assertions (`agda --version`, `lean --version`,
`lean-toolchain`); the Agda receipt's `apt-cache show` index-SHA line no longer
fits (the package is baked in), so replace it with the image digest and the
image label `io.hyperpolymath.checker.package`; update the `DEVIATION (§6)`
comments (they already point at PN-7) and the actions lock if `container:`
changes it; then record a new receipt from a run on the merge commit. The images run as the non-root user `prover` (uid 1001, the uid of GitHub-hosted runners' `runner` user). A job `container:` using them may therefore need `options: --user root` for `actions/checkout`, as resource-algebra's Rocq leg sets today (`.github/workflows/proofs.yml`, `rocq-leg` `container:` block, with the comment "The image's user cannot write the runner's workspace"). Whether these images need it is untested.

== Open questions

. *Rocq consolidation.* Rocq already runs in the upstream
`rocq/rocq-prover:9.3.0@sha256:97a68f23…`. Should it be rebuilt here too, for
one provenance story, or stay upstream?
. *Reproducibility.* The Agda image installs from a fixed Debian snapshot, but
the Lean image's apt layer follows live trixie, and neither build is bit-for-bit
reproducible. Is a digest of a published image enough, or does the estate want
rebuild-and-compare?
. *Guix alternative.* The owner noted a Guix pack and did not choose it. Revisit
if reproducible builds become a requirement.
. *Snapshot timestamp.* `SNAPSHOT_TS` in `agda/Containerfile` is unverified.
. *Name.* Check `prover-images` against `gv-clade-index`; settle clade, IS/IS-NOT
and licence (MPL-2.0 used as a placeholder; a licence is the owner's call).
. *Action pins.* `build.yml` uses only refs found in resource-algebra's
`actions.lock` and plain `docker` commands; the `actions/attest` version is
unconfirmed. Re-pin with estate tooling.
. *Hardening (unbuilt).* The two-stage CA copy in `agda/Containerfile` and the `USER prover` in both files were added to satisfy SonarCloud (clear-text URI, root user); neither has been built or run.
. *Image user and extra libraries.* Whether Lean needs `libgmp10` (included as a
precaution) is untested.

== Validation so far

[cols="2,3",options="header"]
|===
| Check | Result
| `actionlint` v1.7.7 on `build.yml` | exit 0
| `yq` parse of `build.yml` and `dependabot.yml` | ok (before they were carried as listings)
| `hadolint` | not run: the release binary downloaded but no published sha256 could be fetched, so it was not executed
| `docker pull` of the base by digest | succeeded, digest matched
| `docker build` agda, lean | *failed* at `apt-get update` (exit 100) (re-tried after the hardening change, same result; the agda failure is in the new `certs` stage): the sandbox's build network cannot reach Debian mirrors; snapshot.debian.org and the Lean release download are unverified
| smoke tests (`agda --version`, `lean --version`) | not run: images unbuilt
|===

== Draft CI files (listings)

These two files are carried as listings, not as standalone YAML files, so no
scanner in resource-algebra (SonarCloud, workflow linters, Dependabot,
lock-sync, KYAML checks) treats them as live configuration. In the target
repository save the first as `.github/workflows/build.yml` and the second as
`.github/dependabot.yml` (the estate KYAML rule allows `.yml` there because
GitHub demands the name). Both are DRAFT and UNTESTED apart from `actionlint`
v1.7.7 on `build.yml` (exit 0) in the authoring sandbox, run before the
listing was carried here and before `${{ }}` expressions were moved out of
`run:` blocks, so it is stale for this exact text.

=== `.github/workflows/build.yml`

[source,yaml]
----
# DRAFT, UNTESTED (actionlint only). Handoff from resource-algebra PN-7.
# SPDX-License-Identifier: MPL-2.0
name: Build prover images
on:
push:
branches: [main]
paths: ['agda/**', 'lean/**', '.github/workflows/build.yml']
pull_request:
paths: ['agda/**', 'lean/**', '.github/workflows/build.yml']
workflow_dispatch:
permissions:
contents: read
jobs:
build:
name: Build ${{ matrix.image }}
runs-on: ubuntu-latest
timeout-minutes: 30
strategy:
fail-fast: false
matrix:
include:
- image: agda
checker_cmd: agda --version
checker_expect: 'Agda version 2.6.4.3'
- image: lean
checker_cmd: lean --version
checker_expect: 'version 4.35.0,'
permissions:
contents: read
packages: write # push to GHCR (not granted on pull_request runs, see push gate)
id-token: write # sign the provenance attestation
attestations: write
env:
IMAGE: ${{ matrix.image }}
REGISTRY_IMAGE: ghcr.io/hyperpolymath/prover-images/${{ matrix.image }}
steps:
# Only action refs with evidence: SHA from resource-algebra's actions.lock
# (checkout v7.0.1; attest ref present there, its version NOT confirmed).
# Docker is driven by plain `docker` commands so no unverified action SHA
# is invented. Re-pin with the estate's tooling when the repo exists.
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- name: Build
run: |
set -euo pipefail
docker build --pull=false --file "$IMAGE/Containerfile" \
--tag "$REGISTRY_IMAGE:candidate" "$IMAGE"
- name: Smoke test the checker inside the image
env:
CHECKER_CMD: ${{ matrix.checker_cmd }}
CHECKER_EXPECT: ${{ matrix.checker_expect }}
run: |
set -euo pipefail
out="$(docker run --rm "$REGISTRY_IMAGE:candidate" bash -c "$CHECKER_CMD")"
echo "$out"
grep -F "$CHECKER_EXPECT" <<<"$out"
- name: Log in to GHCR
if: github.event_name != 'pull_request'
env:
GH_TOKEN: ${{ github.token }}
GH_ACTOR: ${{ github.actor }}
run: echo "$GH_TOKEN" | docker login ghcr.io -u "$GH_ACTOR" --password-stdin
- name: Push and record the digest
id: push
if: github.event_name != 'pull_request'
env:
SOURCE_SHA: ${{ github.sha }}
CHECKER_CMD: ${{ matrix.checker_cmd }}
CHECKER_EXPECT: ${{ matrix.checker_expect }}
run: |
set -euo pipefail
docker tag "$REGISTRY_IMAGE:candidate" "$REGISTRY_IMAGE:sha-$SOURCE_SHA"
docker push "$REGISTRY_IMAGE:sha-$SOURCE_SHA"
digest="$(docker inspect --format '{{index .RepoDigests 0}}' "$REGISTRY_IMAGE:sha-$SOURCE_SHA" | sed 's/.*@//')"
case "$digest" in sha256:[0-9a-f]*) ;; *) echo "::error::no digest: $digest"; exit 1;; esac
[ "${#digest}" -eq 71 ] || { echo "::error::bad digest length: $digest"; exit 1; }
echo "digest=$digest" >> "$GITHUB_OUTPUT"
{
echo "## Prover image: $IMAGE"
echo ""
echo "- image: \`$REGISTRY_IMAGE@$digest\`"
echo "- source commit: \`$SOURCE_SHA\`"
echo "- smoke test: \`$CHECKER_CMD\` matched \`$CHECKER_EXPECT\`"
echo "- consumer pin: \`container: image: $REGISTRY_IMAGE@$digest\`"
} >> "$GITHUB_STEP_SUMMARY"
- name: Attest build provenance
if: github.event_name != 'pull_request'
uses: actions/attest@508db95dd578ae2727ebd6217d5ba78e4fbda05d # version unconfirmed
with:
subject-name: ${{ env.REGISTRY_IMAGE }}
subject-digest: ${{ steps.push.outputs.digest }}
push-to-registry: true
----

=== `.github/dependabot.yml`

[source,yaml]
----
# DRAFT, UNTESTED. Bumps the digest-pinned base images. Each bump is a PR that
# must rebuild, pass the smoke test and publish a new digest; consumers then
# take that digest by their own PR. Note: the estate's KYAML rule allows .yml
# here because Dependabot demands the name.
version: 2
updates:
- package-ecosystem: docker
directory: /agda
schedule:
interval: weekly
- package-ecosystem: docker
directory: /lean
schedule:
interval: weekly
- package-ecosystem: github-actions
directory: /
schedule:
interval: weekly
----
76 changes: 76 additions & 0 deletions docs/handoff/prover-images/agda/Containerfile
Original file line number Diff line number Diff line change
@@ -0,0 +1,76 @@
# DRAFT, UNBUILT, UNTESTED. Handoff from resource-algebra PN-7 (2026-11-18).
# SPDX-License-Identifier: MPL-2.0
#
# Agda 2.6.4.3 for PROOF-POLICY §8.2 receipts. Same binary resource-algebra's
# proofs.yml installs today: Debian trixie agda-bin 2.6.4.3-1+b2.
#
# Base digest verified against the Docker Hub API on 2026-11-18 (the manifest
# list digest of library/debian:trixie-slim, last_updated 2026-11-05).
#
# Stage 1: debian:trixie-slim ships no CA bundle, so apt cannot use https yet.
# Take ca-certificates from the base image's own default sources and hand only
# the CA files to the final stage.
FROM debian:trixie-slim@sha256:a72b4433de1cf7d6bae0c4cee74d0547f58601a643b3375f070c51600d63b6b2 AS certs
RUN set -eu; \
apt-get update; \
apt-get install --no-install-recommends -y ca-certificates; \
rm -rf /var/lib/apt/lists/*

# Final stage.
FROM debian:trixie-slim@sha256:a72b4433de1cf7d6bae0c4cee74d0547f58601a643b3375f070c51600d63b6b2

COPY --from=certs /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/ca-certificates.crt
COPY --from=certs /usr/share/ca-certificates /usr/share/ca-certificates

# UNVERIFIED: snapshot.debian.org was unreachable from the authoring sandbox
# (proxy 403), so this timestamp is a guess that the package exists at or after
# trixie's current state. The build FAILS LOUDLY if it does not: apt cannot
# find agda-bin=2.6.4.3-1+b2. Verify before first build:
# https://snapshot.debian.org/archive/debian/<TS>/pool/main/a/agda/
ARG SNAPSHOT_TS=20261105T000000Z
ARG AGDA_VERSION=2.6.4.3
ARG AGDA_PKG_VERSION=2.6.4.3-1+b2

# Replace the live mirror with the fixed snapshot. Packages are still checked
# against Debian's signed Release files (Check-Valid-Until is off only because
# snapshot Release files age out of their Valid-Until window by design).
RUN set -eu; \
rm -f /etc/apt/sources.list /etc/apt/sources.list.d/*; \
printf '%s\n' \
'Types: deb' \
"URIs: https://snapshot.debian.org/archive/debian/${SNAPSHOT_TS}/" \
'Suites: trixie' \
'Components: main' \
'Signed-By: /usr/share/keyrings/debian-archive-keyring.gpg' \
'Check-Valid-Until: no' \
> /etc/apt/sources.list.d/snapshot.sources; \
apt-get update; \
apt-get install --no-install-recommends -y \
"agda-bin=${AGDA_PKG_VERSION}" \
ca-certificates git bash grep sed gawk findutils coreutils perl diffutils; \
apt-get clean; rm -rf /var/lib/apt/lists/*; \
test "$(agda --version)" = "Agda version ${AGDA_VERSION}"

# Tools used by resource-algebra's Agda job: bash scripts, find/sort/xargs/
# sha256sum (findutils, coreutils), sed/paste/cut, perl (scan-postulates.pl),
# git (checkout), dpkg-query/apt-cache (receipt step; dpkg and apt are in base).

# Non-root user. uid 1001 is the uid of GitHub-hosted runners' `runner` user,
# so workspace ownership lines up. A job `container:` may still need
# `options: --user root` for actions/checkout; UNTESTED (see README.adoc).
RUN useradd --create-home --uid 1001 --user-group prover
USER prover
WORKDIR /home/prover
RUN agda --version

LABEL org.opencontainers.image.title="prover-images/agda" \
org.opencontainers.image.description="Agda ${AGDA_VERSION} (Debian agda-bin ${AGDA_PKG_VERSION}) for digest-pinned proof receipts" \
org.opencontainers.image.source="https://github.com/hyperpolymath/prover-images" \
org.opencontainers.image.licenses="MPL-2.0" \
org.opencontainers.image.version="${AGDA_VERSION}" \
org.opencontainers.image.base.name="docker.io/library/debian:trixie-slim" \
org.opencontainers.image.base.digest="sha256:a72b4433de1cf7d6bae0c4cee74d0547f58601a643b3375f070c51600d63b6b2" \
io.hyperpolymath.checker="agda" \
io.hyperpolymath.checker.version="${AGDA_VERSION}" \
io.hyperpolymath.checker.package="agda-bin ${AGDA_PKG_VERSION}" \
io.hyperpolymath.debian.snapshot="${SNAPSHOT_TS}"
Loading
Loading