1ArchCodeMathsProveDog: one architecture for coding, researching (mathematical or not), experimenting, proving statements and dogfooding it all for dissemination, in one repository per project, with engines that check the parts agree (projected from ias-core)
  • Haskell 94.4%
  • TeX 3.8%
  • Lean 1%
  • CSS 0.8%
Find a file
lamastex b46d23ddb8 project 1archcodemathsprovedog from ias-core 9c053f4489d0f13a99db9fa904d0d59c791c6a8e
projected from git.vake.works/vakeworks/ias-core at 9c053f4489d0f13a99db9fa904d0d59c791c6a8e (tar sha256 f7676183bf0f851795362e8b65a92deb0655a69b55678a72d98b342eaf705b1a); the previous projection was from a08b132fbd1d989b97081b9847a228a14215fb09.
Generated tree: do not edit it here; change ias-core and project again.
2026-11-11 00:37:27 +01:00
app project 1archcodemathsprovedog from ias-core 9c053f4489d0f13a99db9fa904d0d59c791c6a8e 2026-11-11 00:37:27 +01:00
check project 1archcodemathsprovedog from ias-core 80ef9fd3b8a4be53b2cdb4a570549052d34c6e23 2026-11-08 23:25:24 +01:00
codebooks Seed 1archcodemathsprovedog from 1archcodemathsprovedog.tar (sha256 3632e228d1483ff0a22c096d7564e73dcd3496d2a319a424463c3c34d9e17060) 2026-11-08 15:22:46 +01:00
core project 1archcodemathsprovedog from ias-core 9c053f4489d0f13a99db9fa904d0d59c791c6a8e 2026-11-11 00:37:27 +01:00
examples/legal Seed 1archcodemathsprovedog from 1archcodemathsprovedog.tar (sha256 3632e228d1483ff0a22c096d7564e73dcd3496d2a319a424463c3c34d9e17060) 2026-11-08 15:22:46 +01:00
mappings Seed 1archcodemathsprovedog from 1archcodemathsprovedog.tar (sha256 3632e228d1483ff0a22c096d7564e73dcd3496d2a319a424463c3c34d9e17060) 2026-11-08 15:22:46 +01:00
spec project 1archcodemathsprovedog from ias-core 9c053f4489d0f13a99db9fa904d0d59c791c6a8e 2026-11-11 00:37:27 +01:00
src project 1archcodemathsprovedog from ias-core 9c053f4489d0f13a99db9fa904d0d59c791c6a8e 2026-11-11 00:37:27 +01:00
symbols Seed 1archcodemathsprovedog from 1archcodemathsprovedog.tar (sha256 3632e228d1483ff0a22c096d7564e73dcd3496d2a319a424463c3c34d9e17060) 2026-11-08 15:22:46 +01:00
templates project 1archcodemathsprovedog from ias-core 9c053f4489d0f13a99db9fa904d0d59c791c6a8e 2026-11-11 00:37:27 +01:00
test project 1archcodemathsprovedog from ias-core 9c053f4489d0f13a99db9fa904d0d59c791c6a8e 2026-11-11 00:37:27 +01:00
vendor Seed 1archcodemathsprovedog from 1archcodemathsprovedog.tar (sha256 3632e228d1483ff0a22c096d7564e73dcd3496d2a319a424463c3c34d9e17060) 2026-11-08 15:22:46 +01:00
AGENTS.md project 1archcodemathsprovedog from ias-core 9c053f4489d0f13a99db9fa904d0d59c791c6a8e 2026-11-11 00:37:27 +01:00
CHANGELOG.md project 1archcodemathsprovedog from ias-core 9c053f4489d0f13a99db9fa904d0d59c791c6a8e 2026-11-11 00:37:27 +01:00
CITATION.cff Seed 1archcodemathsprovedog from 1archcodemathsprovedog.tar (sha256 3632e228d1483ff0a22c096d7564e73dcd3496d2a319a424463c3c34d9e17060) 2026-11-08 15:22:46 +01:00
LICENSE Seed 1archcodemathsprovedog from 1archcodemathsprovedog.tar (sha256 3632e228d1483ff0a22c096d7564e73dcd3496d2a319a424463c3c34d9e17060) 2026-11-08 15:22:46 +01:00
NOTICE project 1archcodemathsprovedog from ias-core 9c053f4489d0f13a99db9fa904d0d59c791c6a8e 2026-11-11 00:37:27 +01:00
PROVENANCE.json project 1archcodemathsprovedog from ias-core 9c053f4489d0f13a99db9fa904d0d59c791c6a8e 2026-11-11 00:37:27 +01:00
README.md project 1archcodemathsprovedog from ias-core 9c053f4489d0f13a99db9fa904d0d59c791c6a8e 2026-11-11 00:37:27 +01:00
stack.yaml Seed 1archcodemathsprovedog from 1archcodemathsprovedog.tar (sha256 3632e228d1483ff0a22c096d7564e73dcd3496d2a319a424463c3c34d9e17060) 2026-11-08 15:22:46 +01:00
VERSION project 1archcodemathsprovedog from ias-core 9c053f4489d0f13a99db9fa904d0d59c791c6a8e 2026-11-11 00:37:27 +01:00

1ArchCodeMathsProveDog

The name. One architecture (1Arch) for Code, Maths, Prove and Dog. Dog is for dogfooding: we use our own tools and methods on our own work, so what a project claims is also run and checked with the code and engines it describes.

What it is for. Carrying a research project all the way through: research, code, experiment, prove, dogfood and disseminate, in one repository per project, with the engines of IAS checking that the parts agree. The research does not have to be mathematical. A project with no theorems uses the same repository: its sources' claims and their consistency, its code and tests, its write-up, and the one check (ias-check run; with --build, also the PDF, the Lean seal and the tests, which need LaTeX, Lean and your code's tools). Lean is needed only where a project's write-up states theorems: spines/spines.json says which kinds of statement need which checks, and ias-check reports exactly what your own spines.json requires.

Do Where, in your group's repository Checked by
Research claims/: what your sources assert, each citing where it came from ias-assertion-graph validate, ias-consistency check and recheck
Code code/<lang>/, in the language your project needs, with its tests code anchors (Scala today); with --build, the tests in code/<lang>/ for Scala, Haskell or Python, once spines/spines.json declares an active code spine for that language
Experiment the research loop: change a hypothesis, the code or the data, and rerun, until a claim is proven or supported (or refuted); record each run's commit, command and output your tests (the Code row), which --build reruns; the runs themselves are your evidence, not checked by an engine yet
Prove lean/, only where your write-up states theorems the Lean seal (ias-check --build); with no lean/ project, nothing to build
Dogfood you run the checks on your own work, at each commit you want checked ias-check run, which reads your last commit (HEAD) only; nothing runs it for you
Disseminate paper/: the LaTeX paper; slides/: the talk, in Marp with the course's theme (slides/scadamale-marp-theme.css) the paper's PDF (latexmk, ias-check --build, needs paper/main.tex); slides are not checked

Every student project of the course uses this repository; each group works in its own repository and builds on this one.

This repository is generated from ias-core (Apache-2.0) and is never edited here: changes are made in ias-core and projected again. PROVENANCE.json names the ias-core commit and the sha256 of every file.

Two checkouts

A student keeps two folders side by side, and never forks either:

~/1archcodemathsprovedog/   a clone of this repository: the shared tools. Read it; never edit it.
                            git pull gets a new release. With the tools image (Install, below) the
                            commands come in the image; building from source puts them in bin/.
~/<your group's repository>/   your own work: paper/, code/, lean/, claims/, slides/, spines/.
                            Made once from this repository's template; ias-check runs in it.

Your group's repository lives on git.vake.works (private to your group), or on your own GitHub or GitLab, mirrored read-only to git.vake.works (the group README, "Connecting").

What is in it

Part Command What it does
The group repository ias-template templates/group-project/: a LaTeX paper, slides in the course's theme, a spines registry, claims, a Lean starter and AGENTS.md. render seeds a group's repository from it once; after that the group writes every word
The help repository ias-template templates/group-help/: a README and an AGENTS.md giving the question-and-answer thread format, for people and agents. render seeds the group's private <repository>-help once, with the same keys
Symbols ias-symbols symbols/glyphs.json and the package ias-symbol-macros.sty generated from it. Your paper declares its own symbols in paper/vocabulary.json (kind, arity, glyph) and what they mean in paper/structure.json; check holds the laws
Consistency (E1) ias-consistency Can a set of stated constraints all hold together? If not, it names the smallest clashing sets, with an explanation that recheck verifies independently. Instances: legal-jem (generalised JEM), relation-graph (assertion-graph records), OWL axioms
Assertion graph (E2) ias-assertion-graph What texts assert, as typed records with provenance on every edge, content ids (RFC 8785) and a JSON Schema; validate checks your claims/
Codebooks ias-codebook Shared vocabularies as data and the mappings between them: Biolink (chemical and biomedical relations), Wikidata properties, LKIF's norm module, JEM's legal concepts, the IAS event codebook. Codebooks stay data; you never hard-code a concept
Spines ias-multispine, ias-cert-edges, ias-code-anchors lift reads your paper's numbered statements; join reports, per statement, which of the spines spines/spines.json requires hold: Lean (a ledger row's verifies field) and code (anchors with their sha256, read at your own commit)
The one check ias-check All of the above at your last commit, in one report; with --build, also the paper's PDF, the Lean seal and your code's tests

Every command speaks JSON, exits 0 (done), 1 (defects or a refusal) or 2 (usage, or a file that cannot be read), and has a tool card under spec/<part>/AGENTS.md that any agent can read. AGENTS.md at the root is the card for the whole repository; the group template carries its own AGENTS.md for the agents a group uses.

Install

Two ways to get the commands. Use the first unless you have a reason not to.

You need git and Docker (Docker Desktop on macOS and Windows; Docker or Podman on Linux). Nothing is built on your machine. Define the command once per shell (the tag appears only here), then run it from the root of your group's repository, after a commit:

alias onearch='docker run --rm -v "$PWD":/work -w /work docker.io/vakeworks/1arch-tools:956d1d21'
onearch ias-check run
  • Windows, PowerShell: function onearch { docker run --rm -v "${PWD}:/work" -w /work docker.io/vakeworks/1arch-tools:956d1d21 @args }, then onearch ias-check run. In cmd.exe the mount is -v "%cd%:/work". Or use WSL2 (Ubuntu) with Docker Desktop's WSL integration and follow the macOS and Linux lines; keep your repository inside WSL's own file system (~/...), not under /mnt/c: it is much faster and avoids permission and line-ending trouble.
  • Linux with Docker: add --user "$(id -u):$(id -g)" after --rm in the alias, so the report check-report.json belongs to you. With rootless Podman (alias onearch='podman run ...'), add --userns=keep-id instead.
  • macOS: nothing to add; Docker Desktop maps the files to you.
  • Every command of this repository runs the same way, with this repository's files inside the image at /opt/1arch (its $ONEARCH); for example onearch ias-template keys /opt/1arch/templates/group-project.
  • The same image is git.vake.works/ias/1arch-tools:956d1d21. One image serves Intel/AMD and ARM machines.
  • The tag names the release of this repository the commands were built from; a tag never moves, and each new release says in CHANGELOG.md which tag to use.
  • The image checks everything except --build: it holds no Lean and no TeX. ias-check run --build (the paper's PDF, the Lean seal and your tests) needs the fuller course image, announced when it is ready, or the tools on your own machine.

A clone of this repository is then optional: keep one to read the templates, the tool cards and CHANGELOG.md.

Building from source

For those who prefer to build the commands themselves. You need git and Haskell's stack (https://docs.haskellstack.org); it is tested on Linux, and should work on macOS (Apple silicon too, with the Xcode command-line tools; the first step, stack's download of the compiler, is the long one); on Windows use WSL2. Use a recent stack: an old one (it warns that it "has not been tested with GHC versions above 9.0") cannot check the package index's signatures and stops with "root.json does not have enough signatures"; run stack upgrade, or install stack anew with GHCup, then build again. Once:

Clone it wherever you keep your work (the lines below work in any folder), then build inside the clone:

git clone https://git.vake.works/ias/1archcodemathsprovedog.git
cd 1archcodemathsprovedog
stack build --copy-bins --local-bin-path "$PWD/bin"

The first build takes a while (it fetches the compiler and the libraries). Then, in every shell you work in, set ONEARCH to that clone's folder (from inside it, $PWD is that folder):

export ONEARCH="/the/folder/of/your/clone/1archcodemathsprovedog"
export PATH="$ONEARCH/bin:$PATH"

ias-check finds the other commands in its own folder ($ONEARCH/bin) and the Lean seal and the codebooks through $ONEARCH. After each git pull in $ONEARCH, run the stack build line again.

stack test runs the laws: every engine's guarantees are checked, with a canary that must fail for each.

How a group works with it

The commands below run in your group's repository, after Install. With the tools image, put onearch (the alias of Install) in front of each one, and read $ONEARCH as /opt/1arch.

  1. Get your repository.
    • In the course: the course team has seeded it from the template on git.vake.works. Clone it beside $ONEARCH (its address is in your group's invitation).
    • Anyone else: render the template once, then make it a git repository:
      ias-template keys   $ONEARCH/templates/group-project > KEYS.json     # then edit the values
      ias-template render $ONEARCH/templates/group-project KEYS.json > seed.tar
      mkdir my-project
      tar -xf seed.tar -C my-project
      cd my-project
      git init
      git add -A
      git commit -m "Seed from 1ArchCodeMathsProveDog's template"
      
    Your repository then holds paper/, slides/, spines/, claims/, lean/ and AGENTS.md. It is yours: nobody but your group pushes to its main branch.
  2. Write the paper in paper/main.tex.
    • Put a \label on each statement's \begin line, with its kind as prefix: Dfn-, Lem-, Thm-, Prp-, Cor-, Rmk-, Exm-, Axm-, Cnj-.
    • Write symbols with the glyphs of ias-symbol-macros.sty: \bbR, \cX, \frA, two letters or more.
    • Declare your own symbols in paper/vocabulary.json and what they mean in paper/structure.json, each with the label of the definition that introduces it, then check them:
      ias-symbols check paper/glyphs.json paper/vocabulary.json paper/structure.json
      
  3. Write your code in code/<lang>/, in the language your project needs (Scala, Haskell, Python, ...), with its tests. Build on ours: call these commands, and read and write their JSON.
  4. Experiment, in a loop: state a hypothesis or a claim, run the code that tests it, record the run (commit, command, output), change the hypothesis, the code or the data, and rerun, until the claim is proven or supported, or refuted. Commit as you go.
  5. State what your sources assert as assertion-graph records in claims/, each citing where it came from, then validate them:
    ias-assertion-graph validate --codebook $ONEARCH/codebooks/biolink.json claims/your-records.jsonl
    
  6. Check that your claims hold together, and that the explanation stands:
    ias-consistency check   claims/your-records.jsonl --query minimal-explanation --codebook $ONEARCH/codebooks/biolink.json > R.json
    ias-consistency recheck claims/your-records.jsonl R.json --codebook $ONEARCH/codebooks/biolink.json
    
    A clash is not a failure of your work: the engine names the smallest set of claims that cannot all hold, so the paper can say which source to trust and why.
  7. Prove what your paper states as theorems, if it states any, in Lean, in lean/ (a Lake project pinned to Lean v4.32.0): put /-- ias: verifies Lem-X -/ on the theorem, and the label in lean/ledger.json's "verifies". Build it on your own machine (install Lean with elan, then lake build in lean/), or ask the course team to crunch a commit on the course cluster (step 10). A write-up with no theorem labels has no Lean spine and needs no Lean.
  8. Check it all (dogfood), after committing:
    ias-check run            # add --build where LaTeX, Lean and your code's tools are installed
    
    It prints one page and writes check-report.json (derived; never commit it). Exit 0: every check passed and every required edge holds. Exit 1: the page names what to fix. Exit 2: the check could not run (often: commit first). A Lean theorem counts once it is sealed (--build: it builds, has no sorry, and uses only propext, Classical.choice and Quot.sound); until then the report calls it "claimed".
  9. Disseminate: build the paper (cd paper && latexmk) and the slides (npx @marp-team/marp-cli --theme slides/scadamale-marp-theme.css slides/talk.md --pdf; it needs Node.js and Chrome, Edge or Firefox; add --allow-local-files when the slides show local images).
  10. Get help in your group's help repository on git.vake.works, <your repository>-help, private to your group and the course team: one dated markdown file per question, naming the commit you ask about (your repository's IAS-QUESTIONS.md says how, step by step). When we help with code or text, we push a branch help/<topic> to your repository and open a merge request; your group decides whether to merge it.

If you use an AI agent, give it your repository's AGENTS.md: it says the same as this section, for an agent. Every step stays doable by hand.

Worked examples ship with the cards: spec/consistency/examples/ (a legal trilemma; biomedical "treats" against "causes"; Biolink mixins) and templates/group-project/claims/example.jsonl.

What makes a paper cohesive

The paper's labels are the hub. Everything else points at them:

  • the paper's symbols point at the definition that introduces them (structure.json, defined_at);
  • a Lean theorem names the label it verifies;
  • code names the definition it realises (realises: Dfn-X in a source comment, with an anchor in spines/pointers.json);
  • a claim cites the source span it came from, and an explanation cites the claims it uses.

spines/spines.json says what each kind of statement requires; for example, a lean edge for every Thm- and a code edge for every algorithm's Dfn-. A paper is cohesive when every required edge exists and holds at one commit of your repository, and every law passes.

The spine of spines is built and tested: your write-up's statement spine joined with its Lean spine and its code spine, one row per statement (ias-multispine join), with the Lean seal and the code anchors read at your own commit. ias-check run runs it, with the symbols, claims and consistency checks, and prints one report.

Releases and refreshing

Each release of this repository is tagged with its date (v2026.11.10; v2026.11.10.2 for a second release the same day). VERSION names the release you have, and CHANGELOG.md says, for each release, what is new and what a group must do. Your group's repository names the release it was made with in its ENGINES file. After each git pull here (and the stack build line again, if you build from source), in your group's repository:

ias-template refresh     # copies again only the files that are ours (below)
git add ENGINES paper/ias-symbol-macros.sty paper/glyphs.json
git commit -m "Refresh to 1Arch <the version it printed>"

Ours are paper/ias-symbol-macros.sty, paper/glyphs.json and ENGINES. refresh never touches your own files; it prints each of ours as unchanged, updated or added. It finds this repository through $ONEARCH (or --onearch DIR). ias-check run prints the release it runs with, and warns when your ENGINES, or one of those files, differs from it; a warning never changes the exit code.

What is coming

Stated plainly, so nobody relies on it before it ships:

  • The course image. One container image with Lean, Mathlib, TeX and these engines, so ias-check run --build runs the same on Linux, macOS and Windows, and on clusters with Apptainer.
  • Cluster recipes (Slurm with Apptainer; Kubernetes) for heavy Lean builds and Spark runs on your own resources.
  • Code edges in more languages than Scala. Code anchors are read at your own commit today, but only Scala declarations are recognised.
  • The analysis spine. E1's answers to the questions your paper states, as a spine of the join.

Licence

Apache-2.0 (LICENSE, NOTICE). Copyright 2026 VakeWorks AB. Third-party data keeps its own licence, recorded in NOTICE and next to it under vendor/. Data whose licence is not compatible with Apache-2.0 is never shipped here; you read it as a separate file with --codebook. Your group's paper is under the licence your group chooses (CC BY 4.0 is suggested).