- Haskell 94.4%
- TeX 3.8%
- Lean 1%
- CSS 0.8%
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. |
||
|---|---|---|
| app | ||
| check | ||
| codebooks | ||
| core | ||
| examples/legal | ||
| mappings | ||
| spec | ||
| src | ||
| symbols | ||
| templates | ||
| test | ||
| vendor | ||
| AGENTS.md | ||
| CHANGELOG.md | ||
| CITATION.cff | ||
| LICENSE | ||
| NOTICE | ||
| PROVENANCE.json | ||
| README.md | ||
| stack.yaml | ||
| VERSION | ||
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.
The tools image (recommended: macOS, also Apple silicon, Windows and Linux)
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 }, thenonearch 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--rmin the alias, so the reportcheck-report.jsonbelongs to you. With rootless Podman (alias onearch='podman run ...'), add--userns=keep-idinstead. - 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 exampleonearch 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.mdwhich 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.
- 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"
paper/,slides/,spines/,claims/,lean/andAGENTS.md. It is yours: nobody but your group pushes to its main branch. - In the course: the course team has seeded it from the template on git.vake.works. Clone it beside
- Write the paper in
paper/main.tex.- Put a
\labelon each statement's\beginline, 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.jsonand what they mean inpaper/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
- Put a
- 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. - 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.
- 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 - Check that your claims hold together, and that the explanation stands:
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.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 - 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 inlean/ledger.json's"verifies". Build it on your own machine (install Lean with elan, thenlake buildinlean/), 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. - Check it all (dogfood), after committing:
It prints one page and writesias-check run # add --build where LaTeX, Lean and your code's tools are installedcheck-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 nosorry, and uses only propext, Classical.choice and Quot.sound); until then the report calls it "claimed". - 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-fileswhen the slides show local images). - 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'sIAS-QUESTIONS.mdsays how, step by step). When we help with code or text, we push a branchhelp/<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-Xin a source comment, with an anchor inspines/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 --buildruns 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).