Skip to content
Merged
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
134 changes: 0 additions & 134 deletions .github/workflows/contract.yml

This file was deleted.

183 changes: 1 addition & 182 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -167,15 +167,7 @@ Milestone completion is recorded in the progress journal,
- **All work lands on `main` directly.** No feature branches, no pull
requests, no code review handoff. Commit + push.
- **No CI / GitHub Actions blocking merges.** The local test suite is the
authority — `make test` must be green before pushing. There IS one workflow
now (`.github/workflows/contract.yml`, derived-alg-geo-lean #170) and it
changes nothing about that rule: it blocks no merge, gates no branch, and
covers only the statement CLIs on the ingest plane. It exists because those
two files are the half of a cross-repo contract that a sibling repo depends
on, and "green on Chris's Mac" is not evidence a sibling can use. It is
path-filtered to that surface and installs three packages, not the corpus
stack — see the header comment for why it deliberately does not run
`make test`.
authority — `make test` must be green before pushing.
- **`.github/workflows/credo.yml`** runs on every pull request and push to
`main`. It fails a change that adds or edits Markdown outside the §1
allow-list, reads only git metadata, and runs no tests.
Expand Down Expand Up @@ -576,166 +568,6 @@ rule 3 binds every arXMCP planning/analysis document. These bind every agent ses
Enforcement is by-reference discipline (no CI linter or schema validator this track); the
consuming tracks (R3 Lean surface, R5 registry) implement and gate on the policy.

### 4.10 Sibling formalization repos — the contract boundary (binding)

arXMCP does not host formalization work. Independent Lean projects do, one per
topic, and the interface is **files exchanged at git tags** — never a runtime
call in either direction.

The first sibling is
[`chris-dare-dev/bridgeland-stab-lean`](https://github.com/chris-dare-dev/bridgeland-stab-lean):
a Lean 4 project pinned to `leanprover/lean4:v4.29.0`, extending
`mattrobball/BridgelandStability`, whose source material is the
`bridgeland-stability` notebook. **Sibling, never a subdirectory, never a
dependency.** Its design lives in that repo's `.claude/decisions/` (seven
ADRs, short); its issue tracker holds the arXMCP-side work too, labelled
`cross-repo` — see that repo's `ADR-0006` for why one tracker and what
triggers a split.

These bind every agent session here:

1. **arXMCP never issues statement identity.** A citation key is minted by a
human in the topic repo and contains **zero corpus-derived bytes** — not
`chunk_id`, not `corpus_version`, not the notebook slug. Not a preference:
`chunk_id` rotates by design (`Makefile:80` — *"NOTE: triggers chunk_id
rotation; follow with make re-embed-all"*), there is no alias table, and
`ingest/store.py:908-910`'s `merge_insert` has `when_matched_update_all` +
`when_not_matched_insert_all` and **no delete arm**, so rotation doubles
rather than fails. An id we mint is an id we break.
2. **arXMCP answers exactly one question about a registry entry:** does this
quote still appear in the corpus, and where. Offline, read-only, via an
ingest CLI per §4.8 rule 2 — never at request time. The answer is a file
the topic repo commits, not a response we serve into someone's build.
`source_span`, which `ingest/schema.py` calls the authoritative resolving
key, is written as literal `None` (`ingest/store.py:599`) and is NULL on
every live row, so resolution matches on a quote hash the topic repo owns.
3. **arXMCP never produces elaboration or axiom evidence about a topic repo's
environment.** Two independent reasons, both current:
- **Wrong environment.** No `lean-toolchain` or `lakefile.toml` exists in
this repo; the REPL runs from an operator-supplied directory outside it,
at a different Lean version than any topic repo pins.
- **The audit's declaration extraction is a regex, not Lean** (issue #382,
first closed 2026-08-04, **reopened and re-closed 2026-08-05** — the
first close left a second, sharper hole open). `_declaration_names`
(`server/handlers/lean_verify.py:604`) recognizes a declaration by the
prefix on its line. `set_option` / `open` / `deriving` are in neither
`_DECL_KEYWORDS` nor `_DECL_MODIFIERS`, so such a line once incremented
**neither** `sites` nor `names` and the `sites == len(names)` fail-safe
never fired. It now increments `sites` but not `names`, so the fail-safe
does fire.

**Round 2 — the physical line is OUR unit, never Lean's.** Lean 4 is
whitespace-insensitive at the command level: the term parser stops at a
command keyword, so one line carries any number of declarations. The
round-1 counting still used `.match()`, which returns at most once, so a
line was worth 0 or 1 sites however many declarations Lean read off it.
Verified against real `leanprover/lean4:v4.29.0`, not reasoned about:

```
def harmless : Nat := 1 axiom evil : False
--> 'harmless' does not depend on any axioms
'evil' depends on axioms: [evil]
```

Pre-fix that returned `(['harmless'], True)` and the record read `clean`
with a live `axiom` inside it. The `namespace` / `section` / `end`
branches were the same hole wearing a different hat — they consumed their
line and `continue`d, so a declaration riding behind a scope command was
not merely unnamed but never counted (`end N axiom evil : False` and
`section axiom evil2 : False` both register their axiom; both confirmed
live). The fix counts **every** whitespace-, line-start- or `]`-preceded
declaration keyword on the line, before any branch can `continue` past
it, and masks string-literal interiors in `_strip_comments` so prose in a
string cannot manufacture a phantom site.

Re-measured against this working tree on 2026-08-05, **after** both
fixes:

| snippet | `_declaration_names` | record |
|---|---|---|
| `theorem harmless …` | `(['harmless'], True)` | audited |
| `set_option … in theorem sneaky …` alone | `([], False)` | **`unknown`** — honest |
| unnamed `instance` + `theorem harmless` | `(['harmless'], False)` | **`unknown`** — honest |
| `set_option … in theorem sneaky …` **+** `theorem harmless` | `(['harmless'], False)` | **`unknown`** — was `clean`, the round-1 hole |
| `deriving instance …` **+** `theorem harmless` | `(['harmless'], False)` | **`unknown`** — honest |
| `/-- doc -/ axiom evil : False` **+** `theorem harmless` | `(['evil', 'harmless'], True)` | both audited |
| `def harmless : Nat := 1 axiom evil : False` | `(['harmless'], False)` | **`unknown`** — was `clean`, the round-2 hole |
| `namespace N theorem t … axiom evil …` | `([], False)` | **`unknown`** — was `clean`, round-2 via the scope branch |

Rows 5–6 are the ones a first fix got wrong: it keyed on the `in`
combinator, which closes `set_option` / `open` / `variable` / `universe` /
`attribute` and leaves `deriving instance`, `alias`, `meta …` and a
same-line doc comment open. The correct characterisation is **count the
declaration keywords the line carries and compare against the names
extractable from it** — it is not about `in`, and it is not about what
sits at the START of the line either. Comment text is stripped and string
interiors masked before matching (`_strip_comments`, `:528`), which is
what makes the whole-line scan safe on prose.

**The recurring lesson, stated once:** every revision of this parser has
failed by assuming a shape (an `in` combinator; a line = a declaration).
Over-counting sites is free — it can only move `complete` True -> False —
so when in doubt, count.

**What remains true, and is the reason this bullet still exists:** the
extraction is still a regex over source text, so the honest bound on what
the axis promises a sibling repo is unchanged. Only Lean knows what a
snippet declared; a future `Environment` diff (recorded for
`verification-contract-e3`) is the real answer.

**Do not describe the empty case as the bug.** `:1258` abstains with
`outcome:"unknown"` and says in as many words *"this is NOT a clean
verdict"*, and `:744` downgrades on `complete=False` with a reason. Both
work as designed. An earlier revision of this section cited the empty path;
that was wrong, and the correction matters because it is the difference
between a design that abstains correctly and one that has a single
unguarded gap. (Post-fix, the empty case's `complete` is now `False` rather
than `True` — the abstention is unchanged, but the reason string it emits
is now the more accurate "could not be named" one.)

Any axis whose environment digest differs from the record's renders
`not_applicable` — never a pass, never a fail.
4. **arXMCP may downgrade a trust axis from its own fresher resolution; it has
no path that raises one.** We can say "this got worse since you published
it." We can never say "this is better than you claimed."

§4.9 applies unchanged to anything re-served from a topic repo: no bare
"verified", no axis inferred from another, and coverage stated as a dated
census rather than implied by the presence of records. A topic repo that mints
ten entries against a 15,000-chunk notebook has covered ~0.07% of it, and the
served surface must say so.

**Do not describe this contract in the present tense.** Most of it is still a
design and a backlog, and the parts that are not are narrow. As of 2026-09-03:

| claim | state |
|---|---|
| an offline resolver answers "does this quote still appear, and where" | **LANDED** — `tools/statement_resolve.py`, derived-alg-geo-lean #170 |
| a minting prefill exists | **LANDED** — `tools/statement_mint.py`, #169. It prefills; it mints no identity and writes nothing to the topic repo, and its output is deliberately invalid until a human fills in the four fields that are theirs |
| the corpus can say which arXiv version it holds | **RECOVERABLE, not yet recovered.** Every row still reads `''`; `tools/notebook_arxiv_version_backfill.py` (#171) can fill the ones arXiv's version history establishes, and has not been run against the live notebooks. The resolver's version guard reports `not_applicable` rather than `current` and stays correct afterwards — a row still reading `''` post-backfill is a row whose version could not be established |
| a `formal_releases` table exists | **LANDED** — `notebooks.db` v6, written by `tools/formal_release_pin.py` (#174). Nothing is pinned on this box yet |
| an `arxmcp://formal/*` resource is registered | **LANDED** — `arxmcp://formal/{notebook}` and `/{key}`, RESOURCES not tools, so `EXPECTED_TOOL_SCHEMA_SHA256` and the BP1 prefix are untouched and `tests/test_formal_resource.py` asserts it (#175). The coverage census now carries its denominator (#179): `corpus_chunks` / `corpus_papers` / `corpus_version` / `corpus_measured_at` / `corpus_source`, read from the notebook's ingest-time `corpus-version.json` marker rather than counted live, so the number is DATED and an unauthenticated `resources/read` opens no dataset. A null denominator names its reason — `no-corpus-marker` (an answer: nothing stamped a size) is a different token from `unavailable` (a fault: a size was stamped and could not be read), and neither is `0`. No ratio is computed: entries are statements and chunks are text chunks |
| anything here reads a `formalization.yaml` | **NO** — `find -iname "*formaliz*"` still returns zero files |
| `enable_lean` | still `False` by default (`server/config.py:208`) |

A row crossing off does not promote the others, and two of these carry a
caveat that matters more than the row does:

* **The pinner's `digest_provenance` reads `self_attested_only` against
v0.1.0, and that is not a pass.** The topic repo gitignores `attest/*`
deliberately (CI regenerates them; a committed copy would be a stale trust
record), so the only digests covering those files live inside the file set —
and a coordinated edit satisfies all of them. The tag message asserts "the
tag object … is the root of trust" in prose and carries no digests for
anything to be rooted in. `tools/formal_release_pin.py` parses a
`-----BEGIN MFC DIGESTS-----` block already; a tag that carries one reads
`git_rooted` and refuses the tamper. Until then the pin says which of the
two it is, on every served record.
* **Serving a record is not verifying one.** The resources re-serve the
producer's entry verbatim and attach generated caveats. arXMCP may DOWNGRADE
an axis from its own fresher information and has no code path that raises
one (ADR-0004).

---

## 5. Directory layout — what lives where
Expand Down Expand Up @@ -802,19 +634,6 @@ arXMCP/
│ │ fills documents.arxiv_version from the OAI-PMH
│ │ arXivRaw version history, windowed by fetched_at;
│ │ abstains rather than guessing (#171)
│ ├── _statement_common.py read-only corpus/registry plumbing shared by the two
│ │ statement CLIs; imports mfc's normalization rather
│ │ than copying it (derived-alg-geo-lean #169/#170)
│ ├── statement_resolve.py the resolution ladder -> resolution/1.0, committed
│ │ into the TOPIC repo by a human (ADR-0001: the seam
│ │ is cold). Offline, read-only, never at request time
│ ├── statement_mint.py prefills a candidate registry entry from a chunk,
│ │ including the printed_number -> chunk lookup that
│ │ existed nowhere. Mints no identity (ADR-0002)
│ ├── formal_release_pin.py
│ │ pins a topic repo's released formalization into
│ │ notebooks.db v6, re-deriving what git can root and
│ │ recording digest_provenance for what it cannot
│ ├── arxiv_fetch.py politeness contract: User-Agent, 503 backoff, 3s sleep
│ ├── fetch_one_paper.py single-paper smoke test of arXiv /e-print/ + LaTeXML
│ ├── fetch_seed.py 50-paper seed fetch (idempotent; ≥45/50 to pass)
Expand Down
Loading
Loading