# jrh13/hol-light architecture

> Architecture diagram of the GitHub repository jrh13/hol-light, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jrh13/hol-light
- Repository: https://github.com/jrh13/hol-light

## Overview

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`](https://github.com/jrh13/hol-light/blob/master/hol.ml) (HOL core), [`tactics.ml`](https://github.com/jrh13/hol-light/blob/master/tactics.ml) (Tactics core), [`hol_loader.ml`](https://github.com/jrh13/hol-light/blob/master/hol_loader.ml) (HOL loader), [`grobner.ml`](https://github.com/jrh13/hol-light/blob/master/grobner.ml) (Algebraic auto)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_bootstrap["Bootstrap"]
  node_hol_loader["HOL loader<br/>startup loader<br/>[hol_loader.ml]"]
  node_hol_lib["HOL lib<br/>runtime support<br/>[hol_lib.ml]"]
  node_parser_printer["Parser/printer<br/>syntax io<br/>[parser.ml]"]
  node_numeric_backends["Bignums<br/>numeric backend<br/>[bignum_num.ml]"]
end

subgraph group_kernel["Kernel"]
  node_hol_kernel["HOL core<br/>trusted kernel<br/>[hol.ml]"]
  node_theorems["Theorems<br/>proof objects<br/>[theorems.ml]"]
  node_drule["Derived rules<br/>kernel rules<br/>[drule.ml]"]
  node_types_defs["Types/defs<br/>kernel defs<br/>[define.ml]"]
end

subgraph group_automation["Automation"]
  node_tactics_core["Tactics core<br/>proof engine<br/>[tactics.ml]"]
  node_simplifier["Simplifier<br/>rewriting automation<br/>[simp.ml]"]
  node_search_engines["Search engines<br/>first-order provers<br/>[firstorder.ml]"]
  node_algebraic_auto["Algebraic auto<br/>decision procedures<br/>[grobner.ml]"]
  node_domain_solvers["Domain solvers<br/>specialized engines<br/>[cadical.ml]"]
  node_formal_ineqs["Formal inequalities<br/>verification pipeline<br/>[m_verifier.hl]"]
end

subgraph group_libraries["Libraries"]
  node_logic_library["Logic library<br/>theory pack<br/>[fol.ml]"]
  node_general_library["General library<br/>math library<br/>[analysis.ml]"]
  node_math_theories["Math theories<br/>theory packs<br/>[arithprov.ml]"]
end

subgraph group_tooling["Tooling"]
  node_proof_tracing["Proof tracing<br/>instrumentation<br/>[tracer.ml]"]
  node_mcp["MCP bridge<br/>external integration<br/>[server.py]"]
end

subgraph group_user["User layer"]
  node_examples["Examples<br/>worked proofs<br/>[bitblast.ml]"]
  node_tutorial["Tutorial<br/>learning material<br/>[HOL_basics.ml]"]
  node_help_docs["Help docs<br/>reference docs<br/>[ARITH_TAC.hlp]"]
end

node_hol_loader -->|"loads"| node_hol_lib
node_hol_loader -->|"configures"| node_parser_printer
node_hol_loader -->|"selects"| node_numeric_backends
node_hol_lib -->|"boots"| node_hol_kernel
node_parser_printer -->|"feeds"| node_hol_kernel
node_hol_kernel -->|"defines"| node_theorems
node_theorems -->|"derives"| node_drule
node_drule -->|"extends"| node_types_defs
node_types_defs -->|"used by"| node_tactics_core
node_drule -->|"consumed by"| node_tactics_core
node_tactics_core -->|"invokes"| node_simplifier
node_simplifier -->|"feeds"| node_search_engines
node_simplifier -->|"invokes"| node_algebraic_auto
node_search_engines -->|"uses"| node_logic_library
node_algebraic_auto -->|"proves in"| node_math_theories
node_general_library -->|"supports"| node_math_theories
node_logic_library -->|"extends"| node_general_library
node_domain_solvers -->|"backends"| node_algebraic_auto
node_formal_ineqs -->|"depends on"| node_math_theories
node_proof_tracing -.->|"observes"| node_tactics_core
node_proof_tracing -.->|"records"| node_hol_kernel
node_mcp -->|"drives"| node_hol_loader
node_mcp -.->|"integrates"| node_proof_tracing
node_examples -->|"demonstrates"| node_math_theories
node_examples -->|"uses"| node_algebraic_auto
node_tutorial -->|"teaches"| node_tactics_core
node_help_docs -.->|"documents"| node_hol_kernel

click node_hol_loader "https://github.com/jrh13/hol-light/blob/master/hol_loader.ml"
click node_hol_lib "https://github.com/jrh13/hol-light/blob/master/hol_lib.ml"
click node_parser_printer "https://github.com/jrh13/hol-light/blob/master/parser.ml"
click node_numeric_backends "https://github.com/jrh13/hol-light/blob/master/bignum_num.ml"
click node_hol_kernel "https://github.com/jrh13/hol-light/blob/master/hol.ml"
click node_theorems "https://github.com/jrh13/hol-light/blob/master/theorems.ml"
click node_drule "https://github.com/jrh13/hol-light/blob/master/drule.ml"
click node_types_defs "https://github.com/jrh13/hol-light/blob/master/define.ml"
click node_tactics_core "https://github.com/jrh13/hol-light/blob/master/tactics.ml"
click node_simplifier "https://github.com/jrh13/hol-light/blob/master/simp.ml"
click node_search_engines "https://github.com/jrh13/hol-light/blob/master/firstorder.ml"
click node_algebraic_auto "https://github.com/jrh13/hol-light/blob/master/grobner.ml"
click node_logic_library "https://github.com/jrh13/hol-light/blob/master/Logic/fol.ml"
click node_general_library "https://github.com/jrh13/hol-light/blob/master/Library/analysis.ml"
click node_math_theories "https://github.com/jrh13/hol-light/blob/master/Arithmetic/arithprov.ml"
click node_domain_solvers "https://github.com/jrh13/hol-light/blob/master/Cadical/cadical.ml"
click node_formal_ineqs "https://github.com/jrh13/hol-light/blob/master/Formal_ineqs/verifier/m_verifier.hl"
click node_proof_tracing "https://github.com/jrh13/hol-light/blob/master/TacticTrace/tracer.ml"
click node_mcp "https://github.com/jrh13/hol-light/blob/master/mcp/server.py"
click node_examples "https://github.com/jrh13/hol-light/blob/master/Examples/bitblast.ml"
click node_tutorial "https://github.com/jrh13/hol-light/blob/master/Tutorial/HOL_basics.ml"
click node_help_docs "https://github.com/jrh13/hol-light/blob/master/Help/ARITH_TAC.hlp"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_hol_loader,node_hol_lib,node_parser_printer,node_numeric_backends toneBlue
class node_hol_kernel,node_theorems,node_drule,node_types_defs toneAmber
class node_tactics_core,node_simplifier,node_search_engines,node_algebraic_auto,node_domain_solvers,node_formal_ineqs toneMint
class node_logic_library,node_general_library,node_math_theories toneRose
class node_proof_tracing,node_mcp toneIndigo
class node_examples,node_tutorial,node_help_docs toneTeal
```

## Components

### Bootstrap

OCaml startup, loading, parsing, printing, and runtime setup.

- [HOL loader](https://github.com/jrh13/hol-light/blob/master/hol_loader.ml): startup loader · Initial loading and environment setup for HOL Light scripts. · `hol_loader.ml`
- [HOL lib](https://github.com/jrh13/hol-light/blob/master/hol_lib.ml): runtime support · Shared execution support used across the interactive prover. · `hol_lib.ml`
- [Parser/printer](https://github.com/jrh13/hol-light/blob/master/parser.ml): syntax io · Parsing and pretty-printing of terms, theorems, and notation. · `parser.ml`
- [Bignums](https://github.com/jrh13/hol-light/blob/master/bignum_num.ml): numeric backend · Numeric implementation choice and integration layer for arithmetic support. · `bignum_num.ml`

### Kernel

Trusted theorem core and primitive inference boundary.

- [HOL core](https://github.com/jrh13/hol-light/blob/master/hol.ml): trusted kernel · Theorem datatype, primitive inference, and logical foundation. · `hol.ml`
- [Theorems](https://github.com/jrh13/hol-light/blob/master/theorems.ml): proof objects · Core theorem operations and proof-object infrastructure. · `theorems.ml`
- [Derived rules](https://github.com/jrh13/hol-light/blob/master/drule.ml): kernel rules · Primitive and derived inference rules over terms and theorems. · `drule.ml`
- [Types/defs](https://github.com/jrh13/hol-light/blob/master/define.ml): kernel defs · Datatype, inductive, and definition support at the logical boundary. · `define.ml`

### Automation

Tactics, decision procedures, and specialized proof engines.

- [Tactics core](https://github.com/jrh13/hol-light/blob/master/tactics.ml): proof engine · Goal transformation, tactical combinators, and proof control. · `tactics.ml`
- [Simplifier](https://github.com/jrh13/hol-light/blob/master/simp.ml): rewriting automation · Rewrite-based simplification and normalization of goals. · `simp.ml`
- [Search engines](https://github.com/jrh13/hol-light/blob/master/firstorder.ml): first-order provers · Automated reasoning layers including first-order search and meson/metis style proving. · `firstorder.ml`
- [Algebraic auto](https://github.com/jrh13/hol-light/blob/master/grobner.ml): decision procedures · Computation, canonicalization, Grobner, and arithmetic automation. · `grobner.ml`
- [Domain solvers](https://github.com/jrh13/hol-light/blob/master/Cadical/cadical.ml): specialized engines · SAT/QBF/linear arithmetic, algebraic, and external-solver-backed decision procedures. · `Cadical/cadical.ml`
- [Formal inequalities](https://github.com/jrh13/hol-light/blob/master/Formal_ineqs/verifier/m_verifier.hl): verification pipeline · 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](https://github.com/jrh13/hol-light/blob/master/Logic/fol.ml): theory pack · Classical logic, resolution, unification, and related foundational theory packs. · `Logic/fol.ml`
- [General library](https://github.com/jrh13/hol-light/blob/master/Library/analysis.ml): math library · Reusable algebra, analysis, sets, numbers, and combinatorics support. · `Library/analysis.ml`
- [Math theories](https://github.com/jrh13/hol-light/blob/master/Arithmetic/arithprov.ml): theory packs · Arithmetic, multivariate analysis, probability, function spaces, and geometry. · `Arithmetic/arithprov.ml`

### Tooling

Tracing, recording, external integration, and helper runtimes.

- [Proof tracing](https://github.com/jrh13/hol-light/blob/master/TacticTrace/tracer.ml): instrumentation · Tracing, recording, and proof-object export tooling. · `TacticTrace/tracer.ml`
- [MCP bridge](https://github.com/jrh13/hol-light/blob/master/mcp/server.py): external integration · Python-based agent interface and checkpoint tooling for external interaction. · `mcp/server.py`

### User layer

Examples, tutorials, and reference material.

- [Examples](https://github.com/jrh13/hol-light/blob/master/Examples/bitblast.ml): worked proofs · Demonstrations and proof scripts spanning many domains. · `Examples/bitblast.ml`
- [Tutorial](https://github.com/jrh13/hol-light/blob/master/Tutorial/HOL_basics.ml): learning material · Introductory and advanced walkthroughs of HOL Light usage. · `Tutorial/HOL_basics.ml`
- [Help docs](https://github.com/jrh13/hol-light/blob/master/Help/ARITH_TAC.hlp): reference docs · Generated command, tactic, and conversion reference tree. · `Help/ARITH_TAC.hlp`

## Connections

- 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.
