How jrh13/hol-light works
1. What this repository is
HOL Light is a small OCaml-based interactive theorem prover. The core architecture is not a server/app split, but a layered proof environment built around the OCaml toplevel and a collection of theory files that are loaded in sequence.
2. Bootstrapping boundary
The root files such as hol.ml, hol_loader.ml, hol_lib.ml, bignum_*, and the parser/printer modules form the startup and integration layer. They set up syntax extensions, numeric backends (num or zarith), loading semantics, and the environment needed to execute theorem scripts.
3. Trusted kernel / proof object core
The lowest logical layer lives in root modules like hol.ml, theorems.ml, drule.ml, tactics.ml, term, thm, ind_types.ml, ind_defs.ml, define.ml, system.ml, and related support files. This is the trusted boundary: everything else ultimately builds on the theorem datatype, primitive inference rules, and kernel-level definitions.
4. Tactic and proof search layer
tactics.ml, simp.ml, firstorder.ml, canon.ml, meson.ml, metis.ml, grobner.ml, compute.ml, and fusion.ml provide automation on top of the kernel. These modules consume goals/theorems and produce derived theorems, but they remain inside the OCaml process and do not call out to a separate prover service.
5. Theory libraries as stacked subsystems
The repository is organized into theory packs under directories like Library, Logic, Arithmetic, Multivariate, Probability, Functionspaces, Quaternion, Quaternions, Model, Unity, and IEEE. These are not applications; they are reusable theorem libraries that extend the core with higher-level mathematics and semantics.
6. Decision procedures and algebraic automation
Several directories encapsulate specialized proof engines:
- Cadical, Minisat, QBF, LP_arith, Rqe, Divstep
- Arithmetic, Complex, EC, GL, Jordan, Boyer_Moore
These act as domain-specific automation layers, often translating HOL goals into external or specialized forms and then reconstructing HOL proofs or certificates.
7. Formal-inequality verification pipeline
Formal_ineqs is a distinct subsystem for verified inequality checking. It contains arithmetic, trigonometric, Taylor, and verifier code plus compiled .hl artifacts and test data. The flow is from informal statements and approximation machinery into a certificate/verifier path that produces HOL-checked results.
8. Proof tracing and recording tools
TacticTrace, ProofTrace, and Proofrecording are instrumentation subsystems. They capture tactic/conversion execution, export traces, and interface with proof object formats or external tooling. These are sidecar tools for analysis and interoperability, not part of the trusted kernel itself.
9. External interaction and automation
The mcp directory contains a Python-based Model Context Protocol server and helpers for talking to HOL Light from external agents. This is an integration boundary for tool use, checkpoint generation, and automated interaction rather than a theorem library.
10. User-facing examples and tutorial material
Examples, 100, and Tutorial are the main consumption layer for users. They demonstrate how the core prover and libraries are used to construct proofs, define theories, and apply tactics across many domains.
11. Documentation and discoverability
Help is a large generated reference tree of HOL Light commands, tactics, and conversion combinators. It mirrors the API surface of the prover and is effectively the searchable documentation layer for the interactive environment.
12. Build, CI, and runtime packaging
Makefile, per-subsystem make.ml files, opam, hol_4*.sh, holtest.mk, holtest_parallel, and .github/workflows/main.yml form the build/test/packaging boundary. The repository supports both source-loaded execution in OCaml and checkpointed standalone runtimes (hol, hol.sh), with CI used to validate the many theory packs.
13. How data flows through the system
The typical flow is: OCaml startup → HOL bootstrap modules → kernel/theory infrastructure → loaded libraries and automation → domain-specific scripts/examples → generated theorem artifacts, traces, or certificates. Most subsystems are pure OCaml modules that exchange HOL terms, theorems, and tactics; only a few paths involve external solvers or checkpointing tools.
14. How to draw the architecture
A good diagram should place the HOL kernel and bootloader at the center, then show layered libraries radiating outward: general logic/math libraries, specialized solvers/decision procedures, then examples, tutorials, verification pipelines, and instrumentation/tooling as adjacent subsystems. The main trust boundary is the kernel plus loader; everything else is proof-producing code built on top of it.
Main entry points: hol.ml HOL core · tactics.ml Tactics core · hol_loader.ml HOL loader · grobner.ml Algebraic auto
Components 22
Bootstrap
OCaml startup, loading, parsing, printing, and runtime setup.
- HOL loader · Initial loading and environment setup for HOL Light scripts.
hol_loader.ml - HOL lib · Shared execution support used across the interactive prover.
hol_lib.ml - Parser/printer · Parsing and pretty-printing of terms, theorems, and notation.
parser.ml - Bignums · Numeric implementation choice and integration layer for arithmetic support.
bignum_num.ml
Kernel
Trusted theorem core and primitive inference boundary.
- HOL core · Theorem datatype, primitive inference, and logical foundation.
hol.ml - Theorems · Core theorem operations and proof-object infrastructure.
theorems.ml - Derived rules · Primitive and derived inference rules over terms and theorems.
drule.ml - Types/defs · Datatype, inductive, and definition support at the logical boundary.
define.ml
Automation
Tactics, decision procedures, and specialized proof engines.
- Tactics core · Goal transformation, tactical combinators, and proof control.
tactics.ml - Simplifier · Rewrite-based simplification and normalization of goals.
simp.ml - Search engines · Automated reasoning layers including first-order search and meson/metis style proving.
firstorder.ml - Algebraic auto · Computation, canonicalization, Grobner, and arithmetic automation.
grobner.ml - Domain solvers · SAT/QBF/linear arithmetic, algebraic, and external-solver-backed decision procedures.
Cadical/cadical.ml - Formal inequalities · Certificate-based inequality verification and numeric approximation pipeline.
Formal_ineqs/verifier/m_verifier.hl
Libraries
Stacked theory packs for logic, arithmetic, analysis, and geometry.
- Logic library · Classical logic, resolution, unification, and related foundational theory packs.
Logic/fol.ml - General library · Reusable algebra, analysis, sets, numbers, and combinatorics support.
Library/analysis.ml - Math theories · Arithmetic, multivariate analysis, probability, function spaces, and geometry.
Arithmetic/arithprov.ml
Tooling
Tracing, recording, external integration, and helper runtimes.
- Proof tracing · Tracing, recording, and proof-object export tooling.
TacticTrace/tracer.ml - MCP bridge · Python-based agent interface and checkpoint tooling for external interaction.
mcp/server.py
User layer
Examples, tutorials, and reference material.
Connections 27
- HOL loader → HOL lib: loads · Loader initializes shared library support.
- HOL loader → Parser/printer: configures · Bootstrapping installs syntax and output machinery.
- HOL loader → Bignums: selects · Loader binds the numeric implementation used by the prover.
- HOL lib → HOL core: boots · Runtime support prepares the trusted kernel environment.
- Parser/printer → HOL core: feeds · Syntax layer feeds terms and theorems into the kernel.
- HOL core → Theorems: defines · Kernel provides the theorem object and primitive inference basis.
- Theorems → Derived rules: derives · Theorem operations feed derived inference rules.
- Derived rules → Types/defs: extends · Primitive rules support definitions and inductive constructions.
- Types/defs → Tactics core: used by · Tactics manipulate goals built from kernel definitions.
- Derived rules → Tactics core: consumed by · Tactics apply kernel rules to transform goals.
- Tactics core → Simplifier: invokes · Core tactical control drives simplification.
- Simplifier → Search engines: feeds · Simplified goals are handed to automated search.
- Simplifier → Algebraic auto: invokes · Simplification dispatches to arithmetic and algebraic decision procedures.
- Search engines → Logic library: uses · Search engines rely on logical theory packs and unification tools.
- Algebraic auto → Math theories: proves in · Automation discharges goals in arithmetic and analysis domains.
- General library → Math theories: supports · Reusable library components are imported by higher mathematics.
- Logic library → General library: extends · Foundational logic libraries feed into broader reusable theory support.
- Domain solvers → Algebraic auto: backends · Specialized solver frontends back the generic automation layer.
- Formal inequalities → Math theories: depends on · Inequality verification builds on analysis and arithmetic libraries.
- Proof tracing → Tactics core: observes · Tracing instruments tactic and conversion execution.
- Proof tracing → HOL core: records · Recording tools can export proof objects from core execution.
- MCP bridge → HOL loader: drives · External agents interact through checkpointed HOL sessions.
- MCP bridge → Proof tracing: integrates · Agent tooling can consume traces and checkpoints.
- Examples → Math theories: demonstrates · Examples exercise the main theory libraries.
- Examples → Algebraic auto: uses · Worked proofs showcase automated tactics and solvers.
- Tutorial → Tactics core: teaches · Tutorial material explains the interactive proof layer.
- Help docs → HOL core: documents · Reference docs mirror the exported API of the prover.