Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
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
27 changes: 26 additions & 1 deletion .github/workflows/agda-meta-checker.yml
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,8 @@ on:
- 'meta-checker/**'
- 'scripts/ci/*agda.sh'
- 'scripts/ci/check-receipt-controls.sh'
- 'scripts/ci/agda-cone-receipt.sh'
- 'scripts/ci/test-agda-cone-receipt.sh'
- '.github/workflows/agda-meta-checker.yml'
# No paths-filter on pull_request: this is a REQUIRED status check, so it must
# report on every PR (a path-filtered required check deadlocks PRs that don't
Expand Down Expand Up @@ -55,7 +57,7 @@ jobs:
GH_TOKEN: ${{ github.token }}
run: |
set -euo pipefail
PATTERN='^(meta-checker/|scripts/ci/(setup-agda|check-agda|check-receipt-controls)\.sh$|\.github/workflows/agda-meta-checker\.yml$)'
PATTERN='^(meta-checker/|scripts/ci/(setup-agda|check-agda|check-receipt-controls|agda-cone-receipt|test-agda-cone-receipt)\.sh$|\.github/workflows/agda-meta-checker\.yml$)'

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Include receipt scripts in the push path filter

When a push to main changes only agda-cone-receipt.sh or test-agda-cone-receipt.sh, this detector never executes because the workflow-level path scripts/ci/*agda.sh matches filenames ending in agda.sh, not either newly listed receipt script. Consequently, direct or merge pushes affecting only this receipt tooling skip the proof workflow despite being classified as relevant here; add these scripts to the push.paths filter (or broaden that filter consistently).

Useful? React with 👍 / 👎.

if [ "${{ github.event_name }}" = "pull_request" ]; then
FILES=$(gh api "repos/${{ github.repository }}/pulls/${{ github.event.pull_request.number }}/files" \
--paginate --jq '.[].filename')
Expand Down Expand Up @@ -85,3 +87,26 @@ jobs:
- name: Type-check meta-checker (PROOF-POLICY §2.1 canonical invocation)
if: steps.detect.outputs.relevant == 'true'
run: bash scripts/ci/check-agda.sh

# PROOF-POLICY §8.2/§8.4: the receipt a PWG-3 grade is derived from. It
# records the toolchain, the flags, the import cone of the theory
# module with a digest per file, and a comment-aware postulate scan of
# that cone. The receipt is printed to the log and the step summary.
- name: Record the §8.2 cone receipt for the theory theorems (Receipt.agda)
if: steps.detect.outputs.relevant == 'true'
env:
AGDA_STDLIB_SHA256: 72ca3ea25094efa0439e106f0d949330414232ec4cc5c3c3316e7e70dd06d431
run: |
set -euo pipefail
bash scripts/ci/test-agda-cone-receipt.sh
receipt="$RUNNER_TEMP/agda-cone-receipt.json"
(cd meta-checker && bash ../scripts/ci/agda-cone-receipt.sh src/Echidna/Receipt.agda) > "$receipt"
cat "$receipt"
{
echo '## PROOF-POLICY §8.2 cone receipt (Receipt.agda)'
jq -r '"commit \(.source.commit), \(.toolchain.agda), \(.import_cone.count) modules in the import cone, postulate scan: \(.postulate_scan.result)"' "$receipt"
echo
echo '```json'
cat "$receipt"
echo '```'
} >> "$GITHUB_STEP_SUMMARY"
12 changes: 9 additions & 3 deletions EXPLAINME.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -164,8 +164,13 @@ ECHIDNA-specific anchors:
backends).
* `generated/abi/` — auto-generated C headers from the Idris2 ABI.

The Agda meta-checker provides independent formal verification of the
Rust trust-pipeline properties; see `proofs/agda/`.
The Agda meta-checker (`meta-checker/`) type-checks *models* of the trust
pipeline and two theory results (receipt vs warrant, and proof composition
soundness over an arbitrary logic). A model is not a proof
about the Rust code: under `3-practice/PROOF-POLICY.adoc` §1 the Rust
behaviour is verified with Creusot/Pearlite and Verus on the code, and that is
still open. `proofs/agda/` is a test corpus, not evidence. Status per
obligation: `docs/PROOF-STATUS.adoc`.

== File map: key modules

Expand Down Expand Up @@ -194,7 +199,8 @@ Rust trust-pipeline properties; see `proofs/agda/`.
| `src/ui/tea/`, `src/ui/public/` | TEA sources (compile pipeline unavailable) and working static shell
| `src/abi/` | Idris2 formal specifications (ABI contracts + totality proofs)
| `ffi/zig/`, `src/zig_ffi/` | Zig FFI implementation
| `proofs/agda/` | Agda meta-checker (independent verification of trust properties)
| `meta-checker/` | Agda meta-checker: trust-pipeline models and the receipt/warrant theory (see `docs/PROOF-STATUS.adoc`)
| `proofs/agda/` | Agda test corpus (fixtures for the Agda backend; not evidence, `PROOF-POLICY` §3)
| `tests/` | Integration / property / interface test suites
|===

Expand Down
2 changes: 1 addition & 1 deletion docs/DEBT.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -442,7 +442,7 @@ Fixed so far: the docs and the published site now say "capability present, not
currently engaged" instead of claiming a step that does not run.

Now machine-checked on the specification side:
`+meta-checker/src/Echidna/Integrity.agda+` (`+docs/PROOF-STATUS.adoc+` R9)
`+meta-checker/src/Echidna/Integrity.agda+` (`+docs/PROOF-STATUS.adoc+` R9, an engineering model under the 2026-11-09 §1 classification; the Rust obligation is R1)
proves that verification in its model requires an initialised manifest and
that an uninitialised manifest never verifies. Its explicit hypothesis is
digest-comparison soundness: an accepted comparison implies equal digests.
Expand Down
84 changes: 83 additions & 1 deletion docs/PROOF-STATUS.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -96,6 +96,66 @@ on `+2ab7574+`. *Rocq*: `+open+`, `+BRIDGE-PENDING+`, no receipt. *Lean*:
Grades are derived from receipts, never asserted, and are never flattened into
a percentage. See R5 and R6.

=== Census of theory theorems (`+PROOF-POLICY+` §8.5)

Denominator: the fifteen theory theorems, ten in `+Receipt.agda+` (R11) and five in
`+Composition.agda+` (R6). In `+Receipt.agda+` The file has 18 top-level
proof declarations; three are inhabitation witnesses
(`+warrant-elsewhere+`, `+receipt-in-sharpened-frame+`,
`+one-passing-sample+`) and five are projections, aliases or pairings of
other results (`+postulates-name-an-axiom+`, `+discharge-postulates+`,
`+proven-in-sharpened-frame+`, `+coarse-yet-sharpened+`,
`+warrant-and-receipt+`). Those eight are not graded. `+Composition.agda+`'s five are
`+cut+`, `+explosion+`, `+compose-realised+`, `+detector-cannot-miss+` and
`+detector-must-flag+`.

[width="100%",cols="34%,12%,12%,14%,14%,14%",options="header"]
|===
|Theorem |§5 token |PWG |`+foundation_diverse+` |Rocq leg |Lean leg

|`+receipt-factive+` |`+proven+` |`+PWG-3+` |no |`+open+` |`+open+`
|`+warrant-not-factive+` |`+proven+` |`+PWG-3+` |no |`+open+` |`+open+`
|`+warrant-not-receipt+` |`+proven+` |`+PWG-3+` |no |`+open+` |`+open+`
|`+no-receipt-anywhere+` |`+proven+` |`+PWG-3+` |no |`+open+` |`+open+`
|`+receipt′-factive+` |`+proven+` |`+PWG-3+` |no |`+open+` |`+open+`
|`+frame-receipt-factive+` |`+proven+` |`+PWG-3+` |no |`+open+` |`+open+`
|`+false-sample-rejected+` |`+proven+` |`+PWG-3+` |no |`+open+` |`+open+`
|`+no-free-promotion+` |`+proven+` |`+PWG-3+` |no |`+open+` |`+open+`
|`+no-unconditional-postulate-promotion+` |`+proven+` |`+PWG-3+` |no |`+open+` |`+open+`
|`+no-test-promotion+` |`+proven+` |`+PWG-3+` |no |`+open+` |`+open+`
|`+cut+` |`+argued+` |ungraded |no |`+open+` |`+open+`
|`+explosion+` |`+argued+` |ungraded |no |`+open+` |`+open+`
|`+compose-realised+` |`+argued+` |ungraded |no |`+open+` |`+open+`
|`+detector-cannot-miss+` |`+argued+` |ungraded |no |`+open+` |`+open+`
|`+detector-must-flag+` |`+argued+` |ungraded |no |`+open+` |`+open+`
|===

Census: `+PWG-1+` 0/15, `+PWG-2ii+` 0/15, `+PWG-2i+` 0/15, `+PWG-3+` 10/15,
ungraded 5/15. The five `+Composition.agda+` theorems stay `+argued+` and
ungraded until a source-bound receipt covers that module (R6); the cone
receipt below has `+Receipt.agda+` as its entrypoint only. No result carries `+foundation_diverse+`.

`+PWG-3+` is derived from the receipt
link:reports/2026-11-09-agda-cone-receipt.json[`+2026-11-09-agda-cone-receipt.json+`]
(§8.2, §8.4), written by `+scripts/ci/agda-cone-receipt.sh+`:

* Commit `+4c3ea688+`, with no uncommitted change under `+meta-checker/+`.
The `+meta-checker/+` sources are identical to `+2ab7574+`.
* Agda 2.7.0.1, executable SHA-256 `+6de41437…+` (the repository pin), and
`+agda-stdlib+` 2.1, archive SHA-256 `+72ca3ea2…+`.
* Flags `+--safe --without-K --cubical-compatible+`, entrypoint
`+src/Echidna/Receipt.agda+`, which the kernel accepted.
* An import cone of 211 modules, each with its SHA-256: 1 first-party, 202
from the standard library and 8 from Agda's built-in library.
* A comment-aware scan of the cone that is clean. Its only postulates are
`+Agda.Primitive+`'s universe-level primitives, which belong to the
Agda kernel's trust base.

The `+agda-meta-checker+` job writes the same receipt on every run that
touches these sources. Any change to a cone file invalidates the grade until
a fresh receipt is recorded. The ceiling is `+PWG-3+` while R5's Rocq and
Lean legs are `+open+`.

== Obligations

Grouped by the `+PROOF-POLICY+` §1 mapping, because that is what decides which
Expand All @@ -118,6 +178,10 @@ Annotation is not proof. It is also a *parallel model* ("`NOT a runtime
dependency`"), so even a green Creusot run would cover that model, not the
shipped `+src/rust/+` code, until a refinement or the annotations move onto the
shipped code. *Verus:* not started; no Verus specification or proof exists.
*Known gaps the models hid (2026-11-09 audit):* dispatch accepts an unverified
solver in four ways (an `+Uninitialized+` status, a prover missing from the
manifest, no checker configured, and a `+verify_all()+` error read as an empty
report), and runs the integrity step after proving, not first.
Row stays `+open+` until a Creusot or Verus run on shipped code yields a receipt
with a commit hash.

Expand Down Expand Up @@ -179,7 +243,17 @@ package: `+BojForeign+`, `+OverlayForeign+`, `+TentaclesForeign+`,
packaged modules), `+CoprocessorForeign+` (an orphan whose module name does not
match its path) and `+NeSyAssistTesting+` (does not parse, and states an
empirical claim rather than a provable one). They carry no row until the owner
decides their fate (open question A5).
decides their fate (open question A5). *Audit 2026-11-09 of
`+verification/proofs/idris2/+`:* several modules prove less than their names say:
`+TrustLevelSoundness+` holds by definition of a local function that
disagrees with Rust; `+DispatchCorrectness+` never mentions
`+select_prover+`; `+DispatchOrdering+` proves `+LT 0 1 … LT 0 5+` over an
unused type; `+BasicTotality+` is filler by its own header;
`+ClampTrustBounds+` models a `+Nat → TrustLevel+` function that does not
exist in Rust (the real `+clamp_trust+` is a three-argument range clamp);
`+ProverKindInjectivity+` encodes 79 of 107 variants differently from
`+src/rust/ffi/mod.rs+`, so it is about a different function. Retire or
re-title them; do not count them as evidence.

|===

Expand All @@ -205,6 +279,14 @@ to Idris 2 (or Creusot/Verus on the Rust), not Lean. Calling them "§4
exceptions" is not enough: no §4 exception record (reason, alternative
considered) exists beside them. Owner call: write the §4 records, or move the
statements to Idris 2. Being engineering proofs, they carry no PWG (§8.1).
*Audit 2026-11-09.* What the models say about the code, for R1: `+ConfidenceLattice+` matched
the pre-2026-11-09 trust rule branch for branch and now describes the old
rule; `+IntegrityVerification+` PI-11 (`+solver_integrity_ok+` iff
`+Verified+`) contradicts the four fail-open paths in dispatch, and its
collision-resistance classes assume injectivity on unbounded byte strings,
which real digests cannot satisfy; PO-12 in `+ParetoMaximality+` assumes no
two candidates share all four objective values, which real input can
violate.

|===

Expand Down
1 change: 1 addition & 0 deletions docs/reports/2026-11-09-agda-cone-receipt.json

Large diffs are not rendered by default.

138 changes: 138 additions & 0 deletions scripts/ci/agda-cone-receipt.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,138 @@
#!/usr/bin/env bash
# SPDX-License-Identifier: MPL-2.0
# Copyright (c) 2026 Jonathan D.A. Jewell
#
# agda-cone-receipt.sh ENTRY.agda — the PROOF-POLICY §8.2 receipt for the
# theory theorems in ENTRY: the Agda version, the standard-library pin, the
# flags in force, the import cone with a SHA-256 per file, and a
# comment-aware scan of that cone for postulates, unsafe pragmas and
# primTrustMe (§8.4). Writes one JCS object to stdout.
#
# Run from meta-checker/ after scripts/ci/check-agda.sh, in the environment
# scripts/ci/setup-agda.sh prepares (AGDA_LIBRARIES_FILE, Agda_datadir).
# AGDA_STDLIB_SHA256 names the pinned stdlib archive digest.
#
# The scan reads Agda source with nested {- -} block comments and -- line
# comments removed and {-# #-} pragmas kept. It does not lex string
# literals; a literal holding "{-" would hide text from it, and --safe is
# still the check that refuses escape hatches. The scan is the record §8.4
# asks for, not a replacement for --safe.
#
# Postulates in the Agda data directory (Agda.Primitive's universe-level
# primitives) belong to the Agda kernel's trust base. They are listed in the
# receipt, not counted as findings.
#
# Exit codes: 0 receipt written and the scan is clean, 1 a finding outside
# the kernel's own primitives, 2 cannot run.
set -euo pipefail
export LC_ALL=C.UTF-8

# strip <file>: source with comments removed and pragmas kept.
strip() {
awk '
{ line = $0; out = ""; i = 1; n = length(line)
while (i <= n) {
two = substr(line, i, 2); three = substr(line, i, 3)
if (depth == 0 && inpragma == 0 && three == "{-#") { inpragma = 1; out = out three; i += 3; continue }
if (inpragma == 1 && three == "#-}") { inpragma = 0; out = out three; i += 3; continue }
if (inpragma == 1) { out = out substr(line, i, 1); i++; continue }
if (depth == 0 && two == "--") break
if (two == "{-") { depth++; i += 2; continue }
if (depth > 0 && two == "-}") { depth--; i += 2; continue }
if (depth == 0) out = out substr(line, i, 1)
i++
}
print out }' "$1"

Check warning on line 45 in scripts/ci/agda-cone-receipt.sh

View check run for this annotation

SonarQubeCloud / SonarCloud Code Analysis

Assign this positional parameter to a local variable.

See more on https://sonarcloud.io/project/issues?id=hyperpolymath_echidna&issues=AaHApgITaoI3phGlnUSe&open=AaHApgITaoI3phGlnUSe&pullRequest=479
}

# scan: the escape hatches the receipt records, one "line:text" per hit.
scan() {
{ strip "$1" | grep -nE '(^|[[:space:](){};])postulate($|[[:space:](){};])|\{-#[[:space:]]*(TERMINATING|NON_TERMINATING|NO_POSITIVITY_CHECK|NO_UNIVERSE_CHECK|NON_COVERING)|primTrustMe' || true; }

Check warning on line 50 in scripts/ci/agda-cone-receipt.sh

View check run for this annotation

SonarQubeCloud / SonarCloud Code Analysis

Assign this positional parameter to a local variable.

See more on https://sonarcloud.io/project/issues?id=hyperpolymath_echidna&issues=AaHApgITaoI3phGlnUSf&open=AaHApgITaoI3phGlnUSf&pullRequest=479
}

# Sourced by scripts/ci/test-agda-cone-receipt.sh for strip and scan only.
# shellcheck disable=SC2317 # exit runs only when executed rather than sourced
if [[ "${AGDA_CONE_RECEIPT_FUNCTIONS_ONLY:-}" == 1 ]]; then return 0 2>/dev/null || exit 0; fi

entry=${1:?usage: agda-cone-receipt.sh ENTRY.agda}
flags=(--safe --without-K --cubical-compatible)
if ! command -v agda >/dev/null 2>&1 || [[ ! -f "${AGDA_LIBRARIES_FILE:-}" ]]; then
echo "agda-cone-receipt: pinned Agda setup missing" >&2; exit 2
fi
command -v jq >/dev/null 2>&1 || { echo "agda-cone-receipt: jq missing" >&2; exit 2; }

tmp=$(mktemp -d)
trap 'rm -rf "$tmp"' EXIT

agda --no-default-libraries --library-file "$AGDA_LIBRARIES_FILE" "${flags[@]}" \
--dependency-graph="$tmp/cone.dot" "$entry" > "$tmp/agda.log" 2>&1 \
|| { cat "$tmp/agda.log" >&2; echo "agda-cone-receipt: agda failed" >&2; exit 2; }

data_dir=$(agda --print-agda-data-dir)
# Include roots: the Agda data directory's lib/prim, then every library's
# include directories from the library file (one .agda-lib path per line).
roots=("$data_dir/lib/prim")
while IFS= read -r lib; do
[[ -n "$lib" ]] || continue
libdir=$(dirname -- "$lib")
while IFS= read -r inc; do
roots+=("$libdir/$inc")
done < <(awk '/^include:/ { sub(/^include:[[:space:]]*/, ""); n = split($0, a, /[[:space:]]+/); for (i = 1; i <= n; i++) if (a[i] != "") print a[i] }' "$lib")
done < "$AGDA_LIBRARIES_FILE"

# Module names from the dot file's node labels.
grep -oE 'label="[^"]+"' "$tmp/cone.dot" | sed -E 's/^label="//; s/"$//' | sort -u > "$tmp/modules"
[[ -s "$tmp/modules" ]] || { echo "agda-cone-receipt: empty dependency graph" >&2; exit 2; }

: > "$tmp/cone.jsonl"; : > "$tmp/findings.jsonl"; : > "$tmp/kernel.jsonl"
while IFS= read -r module; do
rel="${module//.//}"
file=""
for root in "${roots[@]}"; do
for ext in agda lagda lagda.md; do
[[ -f "$root/$rel.$ext" ]] && { file="$root/$rel.$ext"; break 2; }
done
done
[[ -n "$file" ]] || { echo "agda-cone-receipt: cannot locate module $module" >&2; exit 2; }
file=$(realpath -- "$file")
case "$file" in
"$(realpath -- "$data_dir")"/*) origin=agda-kernel ;;
"$(realpath -- "$PWD")"/*) origin=first-party ;;
*) origin=library ;;
esac
digest=$(sha256sum "$file" | cut -d' ' -f1)
jq -cn --arg m "$module" --arg o "$origin" --arg d "$digest" '{module: $m, origin: $o, sha256: $d}' >> "$tmp/cone.jsonl"
scan "$file" \
| while IFS=: read -r ln text; do
if [[ "$origin" == agda-kernel ]]; then target="$tmp/kernel.jsonl"; else target="$tmp/findings.jsonl"; fi
jq -cn --arg m "$module" --argjson l "$ln" --arg t "$text" '{module: $m, line: $l, text: ($t | gsub("^\\s+|\\s+$"; ""))}' >> "$target"
done
done < "$tmp/modules"

commit=$(git rev-parse HEAD)
dirty=$(git status --porcelain -- . | head -1)
agda_bin=$(command -v agda)
jq -cnS \
--arg commit "$commit" --arg dirty "${dirty:+yes}" --arg entry "$entry" \
--arg agda "$(agda --version)" --arg agda_sha "$(sha256sum "$agda_bin" | cut -d' ' -f1)" \
--arg stdlib_sha "${AGDA_STDLIB_SHA256:-unrecorded}" \
--argjson flags "$(printf '%s\n' "${flags[@]}" | jq -R . | jq -s .)" \
--slurpfile cone "$tmp/cone.jsonl" --slurpfile findings "$tmp/findings.jsonl" \
--slurpfile kernel "$tmp/kernel.jsonl" '
{
schema_version: 1,
kind: "agda-cone-receipt",
policy: "standards 3-practice/PROOF-POLICY.adoc §8.2, §8.4",
source: {repository: "https://github.com/hyperpolymath/echidna", commit: $commit,
uncommitted_changes_under_entry_dir: ($dirty == "yes"), entrypoint: $entry},
toolchain: {agda: $agda, agda_executable_sha256: $agda_sha,
stdlib_archive_sha256: $stdlib_sha, flags: $flags},
import_cone: {count: ($cone | length), modules: $cone},
postulate_scan: {
method: "comment-aware: nested block and line comments removed, pragmas kept; string literals not lexed",
kernel_primitives: $kernel,
findings: $findings,
result: (if ($findings | length) == 0 then "clean" else "findings" end)
}
}'
[[ ! -s "$tmp/findings.jsonl" ]]
32 changes: 32 additions & 0 deletions scripts/ci/test-agda-cone-receipt.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
#!/usr/bin/env bash
# SPDX-License-Identifier: MPL-2.0
# Copyright (c) 2026 Jonathan D.A. Jewell
# Fixture test for the comment-aware scan in agda-cone-receipt.sh: comments
# (line, block, nested) hide nothing they should not, pragmas stay visible,
# and only the keyword `postulate` counts, not identifiers that contain it.
set -euo pipefail
here=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)
# shellcheck source=scripts/ci/agda-cone-receipt.sh
AGDA_CONE_RECEIPT_FUNCTIONS_ONLY=1 . "$here/agda-cone-receipt.sh"
tmp=$(mktemp -d)
trap 'rm -rf "$tmp"' EXIT
cat > "$tmp/Fx.agda" <<'AGDA'
module Fx where
-- postulate in a line comment
{- postulate in a block {- nested postulate -} still comment postulate -}
x = 1 -- trailing postulate
{-# TERMINATING #-}
postulate
ax : Set
postulates-name : Set
f = primTrustMe
{-# OPTIONS --safe #-}
AGDA
got=$(scan "$tmp/Fx.agda" | cut -d: -f1 | tr '\n' ' ')
want="5 6 9 "
if [[ "$got" == "$want" ]]; then
echo "agda-cone-receipt scan: ok (hits on lines $got)"
else
echo "::error::agda-cone-receipt scan: hits on lines '$got', want '$want'"
exit 1
fi
Loading