---
title: "The Rust spec two-state solution"
tags: ["T-spec"]
date: 2024-09-27
url: https://hackmd.io/tz0RmA4GTAWg9aGDillwMg
---

:::warning
This is WIP draft.
:::

# Summary

Motivated by existing adoption of the FLS in the safety-critical community, we're going to adopt the FLS alongside the Reference as twin specifications for Rust.

Here, we'll discuss the background leading up to that, we'll discuss some of the open questions that leaves, and we'll discuss how a specification for Rust could be more deeply intertwined with lang team process.

# Background

## Motivation for a Rust specification

Some programming languages, including e.g. C, C++, Scheme, Common Lisp, and Algol, have published specifications (or "reports", "references", "standards", etc.). Sometimes these specifications are published by dedicates standards bodies (such as for ANSI Common Lisp, ANSI C89, ISO C23, ISO C++23, etc.). Other times these specifications are published by the language communities themselves (such as for R7RS Scheme).

People have complained for many years, on and off, about the lack of a specification for Rust. Some of these people want a specification so as to support the development of alternative implementations of Rust. Others want it to allow for the qualification of Rust compilers, linters, and other tools so as to facilitate the adoption of Rust in certain safety-critical applications.

Within the project, we have wanted a specification so as to support iteration on the language itself. Often the first step in improving the language is fully understanding what it does today. Having this written down, and having a single document that defines a common set of terminology that our community can share, would help with clear thinking and collaboration as we work to improve Rust.

## History of the Rust Reference

The Rust Reference was started in 2014. It always has been and remains a part of the Rust project. Over the last 10 years, over four hundred different authors have contributed to extending and improving it. It currently contains around 106k words and 114 chapters and subchapters.

When stabilizing new features in the language, we require the authors of those features to author corresponding updates to the Reference before those new features are stabilized. This has helped to keep the content of the Reference accurate with respect to changes in the language.

Other changes to the Reference, especially those that could suggest that the language is guaranteeing some behavior (forever), are reviewed by the lang team and/or by one of its specialized subteams (e.g. T-opsem, T-types). The cost of these reviews can be substantial. The addition of a single sentence or paragraph can easily require an hour of discussion among 6 Rust experts, and correspondingly, the latency in receiving these reviews can be substantial.

While not all text in the Reference has been carefully reviewed by the lang team (or by one of its subteams), the cumulative effect of these reviews over the years means that substantial parts of the Reference have received such review.

The content of the Rust Reference is encoded in Markdown and rendered using [mdBook][], a tool written in Rust and maintained by the project. The mdBook tool is used widely for other documentation within the project.

The Reference was long considered the most equivalent thing to a specification for Rust (though it did not meet the needs of safety-critical industries), and the spec team on 2024-06-13 adopted the Reference as the draft specification of Rust with a plan to extend the Reference to meet the needs of safety-critical industries.

The Reference contains a formal grammar, and for the topics that it covers, its coverage is fairly deep.

[mdBook]: https://github.com/rust-lang/mdBook

## History of the Ferrocene Language Specification (FLS)

Ferrous Systems is a private company that distributes a (minimal) fork of the Rust toolchain that is targeted at users needing the toolchain to have been qualified or certified according to some standards.

To enable these qualifications and certifications, Ferrous Systems compiled the Ferrocene Language Specification (FLS). This document is a combination of parts copied from the Ada Reference Manual, the Rust Reference, the Rust Book, and the Nomicon, along with original authorship.

The git history of the FLS starts in 2022 (though its origins may extend further back). It currently contains around 69k words and is organized into 22 chapters.

The content of the FLS is encoded in [reStructuredText][] format and is rendered using [Sphinx][].

No content in the FLS has been reviewed or approved by any team in the Rust project, and authors of changes to Rust do not update the FLS directly with those changes.

[Sphinx]: https://github.com/sphinx-doc/sphinx
[reStructuredText]: https://en.wikipedia.org/wiki/ReStructuredText

## History of the specification work

Throughout 2022 and 2023, members of the Rust project become increasingly interested in pursuing a specification for Rust. On 2022-12-08, Mara posted [RFC 3355][] which set out a plan for pursuing this. After much discussion, the Rust leadership council approved this RFC, it finished FCP on 2023-07-09, and we opened tracking issue [#113527][].

The lang team adopted overall responsibility for driving this work forward and formed the spec team as a lang subteam on 2023-09-19. The spec team had its first meeting on 2023-11-30.

The original plan for the specification work had been that the Rust Foundation would hire a full time editor to advance this work. The intention was to hire an editor of substantial personal credibility with substantial experience in writing language specifications. This person would have led the process and the authorship, and through that person's substantial and credible experience would have helped to answer the many outstanding questions.

This hiring was to be made possible by the support of contributors to the Foundation that supported the idea of this work on a specification.

For various reasons, hiring a full time editor did not prove possible. Instead, the Foundation allocated part of the time of Joel Marcey, an existing staff member and the technical director at the Foundation, to help with this work.

Starting in July 2024, Connor Horman was hired as a contractor by the Foundation, through the end of the year, to assist with the go forward plan the spec team adopted in June to extend the Reference so as to support safety-critical industries.

[#113527]: https://github.com/rust-lang/rust/issues/113527
[RFC 3355]: https://github.com/rust-lang/rfcs/pull/3355

## The June 2024 go forward plan

On 2024-06-13, the spec team adopted this go forward plan:

1. Adopt the Rust Reference today.
- Keep in our back pocket adopting the FLS in parallel as e.g. the "Rust Safety-Critical Specification", but don't do that today. If we later did that:
- Ferrous Systems would promise to keep the Rust Safety-Critical Specification up to date.
- The project itself would maintain its current processes; only the Reference would be updated by contributors when stabilizing new features in Rust.
2. Reformat one chapter of the Reference ourselves, using the mdbook extension Eric drafted based on Mara's proposed layout.
3. Ask the Foundation to hire a technical writer to churn through the *other* 114 chapters or so and made the same transformation.
4. Expand the coverage of the Reference, in terms of the subjects on which the FLS has some coverage but the Reference doesn't, by adopting the content from the FLS into the Reference.
- In general, narrowing the distance between the Reference and the FLS, starting from the Reference.
5. Work toward associating the tests in the Rust repository with chapters in the Reference.
- Reuse the FLS annotations as much as possible.
- Explore adding a separate test suite for the Reference.

In later discussion, we set October as the point at which we would reevaluate whether the plan was working and whether we wanted to reconsider adopting the FLS in parallel.

## Reconsidering the FLS

Feedback received at recent meetings of the Safety Critical Rust Consortium has prompted a reevaluation of adopting the FLS in parallel. This issue was raised in the spec meeting on 2024-09-19, and the team made a plan to invite members of that consortium to the next meeting to better understand the need.

In the meeting on 2024-09-26, we spoke with members of that consortium, along with a representative of Ferrous Systems, and we learned and confirmed the following.

There is interest among the safety-critical community in adopting Rust. In part, the motivation is financial due to the high cost of qualified C tooling.

This adoption is happening today and is expanding. This ecosystem is still young, as use in this industry was impossible before approximately a year ago when Ferrous Systems delivered the first qualified Rust toolchain.

A qualified tool is one where a vendor has made sufficient *arguments* to an *assessor* to convinced that assessor that the tool meets the standard. This is where the specification is used, is in support of these arguments. There are no hard and fast rules for what is sufficient in making these arguments or what needs to be in the specification for these arguments to succeed. This is up to the individual assessor. The constraint on assessors in accepting these documents is that they take on liability if the tools they qualify cause damages (or are used in a product that causes damages) and are later found to not actually satisfy the specification, e.g. in legal proceedings.

Companies in this industry can be either direct or indirect consumers of the specification. When they're customers of a toolchain vendor and are using that vendor's qualified tool, they are indirect users. But there are cases where these customers become direct users of the specification, e.g. because they need to demonstrate that one of their products adheres to a standard such as MISRA C or ISO 26262 Part 6, and no toolchain vendor has yet qualified a tool in the way needed to demonstrate this. As toolchain vendors do later begin to offer these solutions, that may displace some need for these customers to be direct consumers of the specification.

Some of these customers would prefer that all of their toolchain vendors use the same standard for qualification. The reason for this may be related to how they need to consume the specification directly. E.g., if the compiler they're using is qualified by one vendor under one specification, and the linter they're using is qualified by another vendor under a different specification, and then the customer wants to qualify one of their own products under ISO 26262 Part 6 without a tool that does that exactly, and wants to make an argument to an assessor about how the qualified compiler and qualified linter contribute to meeting the requirements of the separate Part 6 requirements, then they would have to delve into the two separate specifications used to qualify each of those products, and that could make the argument more different to make.

One of these customer documents discussed in the meeting was on the order of hundreds of pages with pervasive citations to individual subsections of the FLS. The effort to produce this document was on the order of one full time person for nine months.

TODO...

## The revised plan

TODO...