Skip to content

Commit fde46e9

Browse files
hyperpolymathclaude
andcommitted
harden(foundation): close closure holes + real guardrail + provenance pins + keystone docs
Foundation provenance audit (Tier 0). Findings + fixes: CLOSURE - examples/All.agda did not import examples.Transport → it was in NO CI closure. Added. - characteristic/N5Falsifier.agda DOES NOT TYPECHECK (unsolved metas) and was silently excluded from characteristic/All.agda. NOT forced green (triage, not a partial hack): in-file known-broken banner, explicit exclusion note in the aggregator, and an expected-failure CI gate so the hole is monitored, not hidden. Its 'SURVIVES' verdict is flagged not-mechanised. GUARDRAIL (the long-documented 'CI-grep-enforced' check never existed) - tools/check-guardrails.sh scans EVERY proofs/agda/**/*.agda (comment-stripped): asserts --safe --without-K, complete escape- pragma/soundness-flag deny-list, no postulate/primTrustMe in code. Negative-self-tested. Wired fail-fast into CI (both jobs). PROVENANCE - absolute-zero pinned to 3ff5cee7… (was floating --depth 1); asserted in CI. - cold-check job: no cache, agda --ignore-interfaces on all 4 roots, parallel to cached job — a green can't be a stale-.agdai artefact. - toolchain version recorded + minimally asserted; exact CI-Agda pin via flake flagged as the tracked P1 (honest, not a fake pin). - misleading hard-coded 'agda2.6.3' cache key corrected. DOCS - docs/foundation.adoc: the trusted-base / trust-surface doc (was missing) — states exactly what is trusted and how each is enforced. - docs/roadmap-gates.adoc: the keystone gates-protocol doc, resolving ~15 dangling canonical references (incl. retractions.adoc's own lead). Faithful to practised protocol; introduces no new claim. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent 2ca3122 commit fde46e9

7 files changed

Lines changed: 487 additions & 9 deletions

File tree

.github/workflows/agda.yml

Lines changed: 98 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -23,19 +23,49 @@ jobs:
2323
sudo apt-get update
2424
sudo apt-get install -y agda git
2525
26+
- name: Record & sanity-check toolchain
27+
run: |
28+
set -e
29+
ver="$(agda --version | head -n1)"
30+
echo "CI Agda: $ver"
31+
echo "Local/flake reproducible Agda is pinned via flake.nix;"
32+
echo "exact-version CI parity (CI-via-flake) is the tracked"
33+
echo "P1 follow-up — see docs/foundation.adoc / proof-debt"
34+
echo "ledger item 'CI Agda pin'. This step makes the version"
35+
echo "VISIBLE and minimally-asserted, not silently floating."
36+
case "$ver" in
37+
*"version 2."*) : ;;
38+
*) echo "::error::unexpected Agda: $ver"; exit 1 ;;
39+
esac
40+
41+
- name: Foundation guardrail (--safe/--without-K, no pragmas/postulates)
42+
run: bash tools/check-guardrails.sh proofs/agda
43+
2644
- name: Fetch Agda standard library (v2.3)
2745
id: stdlib
2846
run: |
2947
STDLIB_DIR="$HOME/agda-stdlib"
3048
git clone --depth 1 --branch v2.3 https://github.com/agda/agda-stdlib.git "$STDLIB_DIR"
3149
echo "stdlib_dir=$STDLIB_DIR" >> "$GITHUB_OUTPUT"
3250
33-
- name: Fetch absolute-zero library
51+
- name: Fetch absolute-zero library (PINNED)
3452
id: absz
53+
env:
54+
# Pinned 2026-05-18 to the known-good revision the suite is
55+
# green against (foundation provenance audit). Bump
56+
# deliberately, never float: an unpinned dependency is an
57+
# unpinned trust boundary.
58+
ABSZ_REF: 3ff5cee7f3fd002378089cd02f0c90a3747b45f0
3559
run: |
3660
ABSZ_DIR="$HOME/absolute-zero"
37-
git clone --depth 1 https://github.com/hyperpolymath/absolute-zero.git "$ABSZ_DIR"
38-
echo "absz_commit=$(git -C "$ABSZ_DIR" rev-parse HEAD)" >> "$GITHUB_OUTPUT"
61+
git clone https://github.com/hyperpolymath/absolute-zero.git "$ABSZ_DIR"
62+
git -C "$ABSZ_DIR" checkout --quiet "$ABSZ_REF"
63+
ACTUAL="$(git -C "$ABSZ_DIR" rev-parse HEAD)"
64+
if [ "$ACTUAL" != "$ABSZ_REF" ]; then
65+
echo "::error::absolute-zero pin mismatch: want $ABSZ_REF got $ACTUAL"
66+
exit 1
67+
fi
68+
echo "absz_commit=$ACTUAL" >> "$GITHUB_OUTPUT"
3969
echo "absz_dir=$ABSZ_DIR" >> "$GITHUB_OUTPUT"
4070
4171
- name: Register libraries for Agda
@@ -71,10 +101,14 @@ jobs:
71101
~/agda-stdlib/**/*.agdai
72102
~/absolute-zero/**/*.agdai
73103
proofs/agda/**/*.agdai
74-
key: agdai-${{ runner.os }}-agda2.6.3-stdlib2.3-absz${{ steps.absz.outputs.absz_commit }}-${{ hashFiles('proofs/agda/**/*.agda') }}
104+
# Key reflects reality: stdlib v2.3 + the PINNED absz commit
105+
# + source hash. (Previously hard-coded a stale "agda2.6.3";
106+
# corrected 2026-05-18. The cold-check job below never uses
107+
# this cache, so a cache anomaly cannot mask a real break.)
108+
key: agdai-${{ runner.os }}-stdlib2.3-absz${{ steps.absz.outputs.absz_commit }}-${{ hashFiles('proofs/agda/**/*.agda') }}
75109
restore-keys: |
76-
agdai-${{ runner.os }}-agda2.6.3-stdlib2.3-absz${{ steps.absz.outputs.absz_commit }}-
77-
agdai-${{ runner.os }}-agda2.6.3-stdlib2.3-
110+
agdai-${{ runner.os }}-stdlib2.3-absz${{ steps.absz.outputs.absz_commit }}-
111+
agdai-${{ runner.os }}-stdlib2.3-
78112
79113
- name: Typecheck full suite
80114
run: agda -i proofs/agda proofs/agda/All.agda
@@ -87,3 +121,61 @@ jobs:
87121

88122
- name: Typecheck examples lane (Gate #3 canonical examples)
89123
run: agda -i proofs/agda proofs/agda/examples/All.agda
124+
125+
# Disclosed known-broken module (foundation audit 2026-05-18):
126+
# characteristic/N5Falsifier.agda has unsolved metas and is NOT
127+
# in any green closure. This gate ASSERTS it still fails, so the
128+
# hole stays monitored: if it ever typechecks, this step fails
129+
# loudly and tells us to register it + drop the xfail.
130+
- name: Expected-failure gate (N5Falsifier is known-broken)
131+
run: |
132+
if agda -i proofs/agda proofs/agda/characteristic/N5Falsifier.agda \
133+
> /tmp/n5.log 2>&1; then
134+
echo "::error::N5Falsifier now typechecks — register it in"
135+
echo "::error::characteristic/All.agda and remove this xfail gate."
136+
exit 1
137+
else
138+
echo "N5Falsifier fails as expected (disclosed in its banner"
139+
echo "and the proof-debt ledger). Hole monitored, not hidden."
140+
fi
141+
142+
cold-check:
143+
# Belt-and-braces: NO interface cache, --ignore-interfaces cold
144+
# build. A green here cannot be a stale-.agdai artefact (matters
145+
# given the documented WSL git-object-corruption risk). Runs in
146+
# parallel with `check`; both must pass.
147+
runs-on: ubuntu-latest
148+
steps:
149+
- name: Checkout
150+
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
151+
152+
- name: Install Agda
153+
run: |
154+
sudo apt-get update
155+
sudo apt-get install -y agda git
156+
157+
- name: Foundation guardrail
158+
run: bash tools/check-guardrails.sh proofs/agda
159+
160+
- name: Fetch pinned libraries
161+
id: libs
162+
env:
163+
ABSZ_REF: 3ff5cee7f3fd002378089cd02f0c90a3747b45f0
164+
run: |
165+
STDLIB_DIR="$HOME/agda-stdlib"
166+
git clone --depth 1 --branch v2.3 https://github.com/agda/agda-stdlib.git "$STDLIB_DIR"
167+
ABSZ_DIR="$HOME/absolute-zero"
168+
git clone https://github.com/hyperpolymath/absolute-zero.git "$ABSZ_DIR"
169+
git -C "$ABSZ_DIR" checkout --quiet "$ABSZ_REF"
170+
mkdir -p "$HOME/.agda"
171+
printf 'name: standard-library\ninclude: %s/src\n' "$STDLIB_DIR" > "$RUNNER_TEMP/sl.agda-lib"
172+
printf 'name: absolute-zero\ninclude: %s/proofs/agda\n' "$ABSZ_DIR" > "$RUNNER_TEMP/az.agda-lib"
173+
printf '%s\n%s\n' "$RUNNER_TEMP/sl.agda-lib" "$RUNNER_TEMP/az.agda-lib" > "$HOME/.agda/libraries"
174+
printf 'standard-library\n' > "$HOME/.agda/defaults"
175+
176+
- name: Cold typecheck (--ignore-interfaces, no cache)
177+
run: |
178+
agda --ignore-interfaces -i proofs/agda proofs/agda/All.agda
179+
agda --ignore-interfaces -i proofs/agda proofs/agda/Smoke.agda
180+
agda --ignore-interfaces -i proofs/agda proofs/agda/characteristic/All.agda
181+
agda --ignore-interfaces -i proofs/agda proofs/agda/examples/All.agda

docs/foundation.adoc

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
= Echo Types — Foundation & Trusted Base
2+
:toc: macro
3+
:toclevels: 2
4+
:sectnums:
5+
:sectnumlevels: 2
6+
:icons: font
7+
8+
[.lead]
9+
What the foundation actually is, exactly what is trusted, and how
10+
each part is mechanically enforced. Created 2026-05-18 after a
11+
foundation provenance audit. This document makes no proof claims; it
12+
states the trust surface so there is no doubt about its boundary.
13+
14+
toc::[]
15+
16+
== The foundational object (deliberately trivial)
17+
18+
`Echo f y := Σ (x : A) , (f x ≡ y)` is *definitionally* the homotopy
19+
fibre. There is no new type former, no axiom, no postulate. The
20+
soundness of the foundation is the soundness of Agda's `Σ` and `≡`
21+
under `--safe --without-K` — nothing more is claimed, and that
22+
triviality is the point, not a weakness. (The self-referential
23+
`echo↔fib` bridge — `fiber` is a same-module restatement — is the one
24+
mathematical place worth hardening; see `docs/retractions.adoc`
25+
R-2026-05-18 and the external-fibre triangulation, tracked P1.)
26+
27+
== Trust surface and its enforcement
28+
29+
[cols="2,3,2", options="header"]
30+
|===
31+
| Trusted claim | How it is enforced (post-2026-05-18) | Residual
32+
33+
| Every module is `--safe --without-K`
34+
| `tools/check-guardrails.sh` scans *every* `proofs/agda/**/*.agda`
35+
(comment-stripped) and asserts the OPTIONS line carries both flags;
36+
wired as a fail-fast CI step in both jobs. Independent of any
37+
`All.agda` closure.
38+
| none
39+
40+
| Zero postulates / zero escape pragmas
41+
| Same script: complete deny-list of escape pragmas + soundness flags
42+
+ `postulate`/`primTrustMe` in code. `--safe` in the typecheck
43+
lanes is the primary guarantee; the script covers files outside
44+
every closure.
45+
| nested `{- -}` not modelled (codebase uses `--` banners); lanes are
46+
the backstop
47+
48+
| The whole development typechecks
49+
| Four CI roots — `All.agda`, `Smoke.agda`, `characteristic/All.agda`,
50+
`examples/All.agda` — now cover *all* registered modules (the two
51+
2026-05-18 closure holes, `examples.Transport` and the
52+
N5 exclusion, are resolved/disclosed below).
53+
| `N5Falsifier` is *known-broken*, see below
54+
55+
| A green build is not a stale-cache artefact
56+
| `cold-check` CI job: no interface cache, `agda --ignore-interfaces`
57+
on all four roots. Runs in parallel with the cached `check` job;
58+
both must pass.
59+
| none
60+
61+
| Dependencies are pinned
62+
| `standard-library` pinned to branch `v2.3`; `absolute-zero` pinned
63+
to commit `3ff5cee7…` (was floating `--depth 1`). Asserted in CI.
64+
| Agda version itself — see *Known limitations*
65+
|===
66+
67+
== Known-broken, disclosed (not hidden)
68+
69+
`proofs/agda/characteristic/N5Falsifier.agda` does **not** typecheck
70+
(`UnsolvedConstraints` / `UnsolvedMetaVariables`, lines ~150–200). It
71+
was historically excluded from `characteristic/All.agda` with no
72+
disclosure — a silent hole found by the 2026-05-18 audit. It is now:
73+
74+
* banner-marked in-file as known-broken, with the "VERDICT … SURVIVES"
75+
line explicitly flagged *not mechanised*;
76+
* explicitly noted as a deliberate exclusion in
77+
`characteristic/All.agda`;
78+
* monitored by an *expected-failure* CI gate — if it ever typechecks,
79+
CI fails loudly and instructs to register it and drop the gate.
80+
81+
It must not be cited as an established Gate-2 nominee until it is
82+
green `--safe --without-K`, zero unsolved metas. Triage, not a partial
83+
hack: left explicit and failing, never forced green.
84+
85+
== Known limitations (tracked, not silent)
86+
87+
. *CI Agda version not exactly pinned.* CI installs Ubuntu's `agda`
88+
(apt); local dev and the Nix flake differ (2.8.0 / flake-pinned).
89+
The CI step *records and minimally asserts* the version (fails on a
90+
wildly wrong major) so it is visible, not silently floating. Exact
91+
parity via *CI-through-the-flake* is the tracked P1 follow-up — the
92+
only honest way to pin Agda reproducibly.
93+
. *External-fibre triangulation* (P1): replace the same-module
94+
`echo↔fib` self-bijection with agreement against an independently
95+
defined fibre, upgrading a triviality to a cross-definition theorem.
96+
. *Cross-assistant kernel check* (P2): confirm the 3-line core in an
97+
independent type-checker (e.g. Cubical Agda's native `fiber`).
98+
99+
== Reproducing the trusted build
100+
101+
[source,sh]
102+
----
103+
# Guardrail (no Agda needed):
104+
bash tools/check-guardrails.sh proofs/agda
105+
106+
# Cold, cache-free typecheck of every root:
107+
agda --ignore-interfaces -i proofs/agda proofs/agda/All.agda
108+
agda --ignore-interfaces -i proofs/agda proofs/agda/Smoke.agda
109+
agda --ignore-interfaces -i proofs/agda proofs/agda/characteristic/All.agda
110+
agda --ignore-interfaces -i proofs/agda proofs/agda/examples/All.agda
111+
----
112+
113+
Pinned inputs: `standard-library` `v2.3`; `absolute-zero`
114+
`3ff5cee7f3fd002378089cd02f0c90a3747b45f0`. Agda: see `flake.nix`
115+
(reproducible) — CI parity is the P1 item above.
116+
117+
== Revision history
118+
119+
* *2026-05-18 — created.* Post foundation provenance audit. Records
120+
the closure-hole closure (`examples.Transport`), the disclosed
121+
N5 known-broken hole, the guardrail script, the `absolute-zero`
122+
pin, the cold-check job, and the open CI-Agda-pin / triangulation
123+
follow-ups. Append-only.

docs/roadmap-gates.adoc

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
= Echo Types — Gates Protocol (Falsifiable Identity Claim)
2+
:toc: macro
3+
:toclevels: 2
4+
:sectnums:
5+
:sectnumlevels: 2
6+
:icons: font
7+
8+
[.lead]
9+
The canonical gates protocol. Created 2026-05-18 to resolve a
10+
long-standing dangling reference: ~15 documents (including
11+
`docs/retractions.adoc`'s own lead, `next-questions.adoc`,
12+
`buchholz-plan.adoc`, the `EI2_*`/`gate-2-*` handoffs, and the
13+
`echo-types/*` papers) cited `roadmap-gates.adoc` as canonical while
14+
the file did not exist. This document states the protocol that was
15+
already being practised; it introduces no new claim and is faithful
16+
to the living instances in `next-questions.adoc`, `retractions.adoc`,
17+
and `echo-types/earn-back-plan.adoc`.
18+
19+
toc::[]
20+
21+
== The identity claim, made falsifiable
22+
23+
The repository asserts that "echo" (loss-with-residue,
24+
`Echo f y := Σ (x:A),(f x ≡ y)`) is a *distinct, characterisable
25+
type-theoretic phenomenon*. That assertion is held **falsifiable**:
26+
each gate below has an explicit pass condition *and an explicit
27+
retraction condition*. A gate whose retraction condition is met
28+
*retracts* the corresponding claim — it does not weaken into a hedge.
29+
Retraction is the mechanism by which the identity claim is made
30+
falsifiable, not a failure of the repository.
31+
32+
== The three gates
33+
34+
[#gate-1]
35+
=== Gate 1 — Distinct phenomenon
36+
37+
Echo is not a renaming of an existing construction (quotient, Galois
38+
connection, lens/optic, refinement type, modal/comonadic type,
39+
provenance semiring). *Pass:* a distinctness witness that survives
40+
reduction attempts to each neighbour. *Retract:* a neighbour
41+
construction expresses the characteristic family without importing
42+
echo-specific primitives. Living instances: `docs/next-questions.adoc`
43+
Gate 1; `docs/adjacency/*`.
44+
45+
[#gate-2]
46+
=== Gate 2 — Characteristic theorems
47+
48+
There exist theorems true of echo that *measure* its content rather
49+
than restate generic Σ-functoriality. *Pass:* a nominee that survives
50+
a sharpened falsifier of the shape that struck down earlier nominees
51+
(collapsing a pseudo-theorem to `proj₂` / a product of independent
52+
restatements). *Retract:* the nominee is shown to be such a product,
53+
or to reduce to thinness of the loss order alone (cf.
54+
`EchoSeparating`, `docs/characteristic.adoc` §"Honest
55+
qualifications").
56+
57+
[#gate-2-nominees]
58+
.Gate 2 nominee table
59+
[cols="1,3,1", options="header"]
60+
|===
61+
| Id | Candidate | Status
62+
63+
| N1–N4
64+
| Earlier nominees (recipe family)
65+
| Audited; documented in `docs/characteristic.adoc` /
66+
`characteristic/IntegrationAudit.agda` — one recipe, "would weaken
67+
in parallel" (recorded, not hidden).
68+
| N3
69+
| `knowledge-and-controlled-degradation`
70+
| *Struck down* by the sharpened falsifier
71+
(`characteristic.IntegrationAudit`).
72+
| N5
73+
| `characteristic.RoleGraded.choreo-grade-commute`
74+
| *NOT adopted.* The falsifier attempt
75+
`characteristic/N5Falsifier.agda` is **known-broken** (unsolved
76+
metas; disclosed in `docs/foundation.adoc`). The "survives" verdict
77+
is *not mechanised*; N5 must not be cited as established.
78+
|===
79+
80+
[#gate-3]
81+
=== Gate 3 — Canonical examples
82+
83+
The phenomenon has worked examples that are not toys. *Pass:* an
84+
example typechecking `--safe --without-K`, zero postulates, exercising
85+
the characteristic structure (e.g. `examples/Transport.agda` block
86+
averaging). *Retract:* every example collapses to a trivial instance.
87+
88+
== Failure action
89+
90+
*Failure is recorded in `docs/retractions.adoc` rather than silently
91+
revised.* When a gate's retraction condition is met:
92+
93+
. add a dated entry to `docs/retractions.adoc` (append-only) stating
94+
trigger, finding, what is retracted, and the replacement;
95+
. edit every affected artefact so *no inflated form survives* in any
96+
document — reframe to the mechanised strength, never delete history;
97+
. earn-back, if attempted, is gated and logged in
98+
`docs/echo-types/earn-back-plan.adoc`; a failed earn-back gate is a
99+
*second negative result*, logged, not a silent revert.
100+
101+
No postulates, no escape pragmas, `--safe --without-K`, ever — a gate
102+
"passed" by weakening these is failed (`tools/check-guardrails.sh`
103+
enforces this independently of any closure; see `docs/foundation.adoc`).
104+
105+
== Relationship to the other living documents
106+
107+
* `docs/next-questions.adoc` — the open questions, each with home
108+
gate, attack path, and explicit retraction condition (the
109+
operational instance of this protocol).
110+
* `docs/retractions.adoc` — the append-only failure log this
111+
protocol's *Failure action* writes to (R-2026-05-18 and its
112+
follow-ups).
113+
* `docs/echo-types/earn-back-plan.adoc` — the gated programme to
114+
convert retracted claims back into theorems (Pillar F).
115+
* `docs/foundation.adoc` — the trusted base and its enforcement.
116+
117+
== Revision policy
118+
119+
Append-only revision history. This document describes the protocol;
120+
it does not record results (those live in `retractions.adoc` /
121+
`next-questions.adoc`).
122+
123+
=== Revision history
124+
125+
* *2026-05-18 — created.* Faithful reconstruction of the
126+
already-practised protocol to resolve the dangling canonical
127+
reference. No new claim introduced.

proofs/agda/characteristic/All.agda

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,12 @@
1111
-- these modules; this file is the CI seam for the lane.
1212
--
1313
-- New characteristic modules should register here.
14+
--
15+
-- DELIBERATE EXCLUSION (disclosed 2026-05-18): `characteristic.N5Falsifier`
16+
-- is NOT imported here because it does not typecheck (unsolved metas;
17+
-- see its in-file broken banner). It is monitored by an
18+
-- expected-failure CI gate and ledgered, not silently dropped. Do not
19+
-- "register" it until it is green `--safe --without-K`.
1420
------------------------------------------------------------------------
1521

1622
module characteristic.All where

0 commit comments

Comments
 (0)