# astrid-runtime/rfcs: the specification layer for Astrid's kernel-to-user-space contract

> The RFC repository for the Astrid runtime is not a library you install. It is where changes to the host ABI, IPC protocol, capability model, manifest schema and VFS semantics get written down first, and where implementations follow the text rather than the other way around.

**astrid-runtime/rfcs** — RFCs for Astrid public contract surfaces.

- Repository: https://github.com/astrid-runtime/rfcs
- Stars: 4,249 · Forks: 8
- Language: Python
- License: Apache-2.0
- Published: 2026-09-23 · Updated: 2026-09-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/astrid-runtime-rfcs

## What astrid-runtime/rfcs is for, and who actually needs it

This repository holds design proposals for changes to Astrid's kernel-to-user-space contract. That phrase covers a specific list: the host ABI, the IPC protocol, the capability model, the manifest schema, VFS semantics, capsule interface standards, and the public API of astrid-sdk. The README is blunt about precedence. RFCs are described as the authoritative specification, and implementations conform to them rather than the reverse.

That ordering matters more than it sounds. When the specification leads, a change to the syscall table or to capability token validation is argued in prose before anyone writes code against it, and the argument is public. When implementations lead, the contract is whatever the current build happens to accept, and downstream capsule authors discover the rules by breaking them.

The audience is narrow. If you are adding or changing a host function in the syscall table in astrid-sys, changing IPC topic conventions or payload schemas, modifying the capability token format or its validation semantics, changing the Capsule.toml manifest schema or dependency resolution, changing VFS path resolution or overlay behavior, defining a new capsule interface standard, or making a breaking change to the astrid-sdk public API, this repository is where you go first. If you are writing a capsule that only consumes existing interfaces, you are a reader of the index, not a contributor to it.

## The RFC process as a pull request pipeline

The workflow is deliberately conventional and has no tooling beyond Git and the hosting platform. You fork the repository, copy 0000-template.md to a path under text/ named 0000-my-feature.md, fill it in with an emphasis on motivation and the reference-level spec, and open a pull request using that same filename. Discussion happens on the pull request, and you revise there.

The interesting step is the last one. When consensus is reached, a maintainer assigns the next sequential number, renames the file to text/NNNN-my-feature.md, and merges. Numbers are not chosen by the author, which removes a class of collisions and makes the index a reliable ordering of when proposals were accepted rather than when they were drafted.

Implementation then proceeds in two places: astrid-sdk, where the types land behind feature flags, and reference capsules. That split is worth noting. The RFC text is the specification, the SDK carries the types, and the capsules demonstrate them. A proposal that merges but never produces SDK types and a reference capsule is specification without a consumer.

The lifecycle has five states. Draft means the pull request is open and under discussion. Active means merged and being implemented in astrid-sdk. Final means implemented and stable, at which point breaking changes require a new RFC rather than an edit to the old one. Withdrawn means closed without merge. Superseded means replaced by a newer RFC, with the replacement noted in the header. The Final state is the one that constrains you most: the text is frozen, and the only way forward is another document.

## How RFC types reach astrid-sdk through feature flags

The README states that each RFC maps to an astrid-sdk feature flag. That is the mechanism connecting a document to a build, and it is the part of this repository with the most direct effect on a downstream project's dependency graph. You opt into a specific RFC's types by naming its flag, or you take everything with all-rfcs.

```toml
# Individual RFC types
astrid-sdk = { version = "0.2", features = ["rfc-1"] }

# All RFC types
astrid-sdk = { version = "0.2", features = ["all-rfcs"] }
```

The flag naming is where the design shows a trade-off. Feature flags are additive in Cargo, so enabling rfc-1 and rfc-2 together is the normal case, and all-rfcs is a convenience that pulls in every RFC type the SDK currently ships. If an RFC reaches Final and a later RFC supersedes it, the old flag's meaning is a question the README does not answer. Nothing in the repository describes whether a superseded RFC's flag is removed, kept as an alias, or left in place with its types intact. Anyone building against an older flag should treat that as unverified and check the SDK's own documentation rather than assuming.

The version pin in the example is 0.2. That is a pre-1.0 line, which is consistent with a contract that is still being specified through numbered proposals rather than settled. Pinning to a specific minor version is the safe posture here.

## Making a first real contribution

There is nothing to install. The repository is documentation and a template, and the README gives no install command because none exists. What you install, if anything, is astrid-sdk in the project that consumes the RFC types. The practical first use is submitting a proposal, and the steps below follow the process section of the README exactly.

Start by forking the repository and creating the file from the template. The naming convention is the literal placeholder 0000 followed by a short slug, and you keep that name through review.

```bash
cp 0000-template.md text/0000-my-feature.md
```

Fill in the document, with the motivation and the reference-level specification carrying the weight. Then open a pull request. The README says to use the filename 0000-my-feature.md in the pull request, so the branch name and the PR title should both make the proposal identifiable. Discussion happens on the pull request itself, not in an issue tracker, and you revise in place.

What you should see if consensus is reached is a maintainer renaming the file to text/NNNN-my-feature.md with the next sequential number and merging it, at which point the status moves to Active and the types begin landing in astrid-sdk behind a feature flag. If consensus is not reached, the pull request closes and the RFC is Withdrawn.

For consumers rather than authors, the first real use is reading the index. It currently lists a single entry, 0001, titled RFC Process, with status Active. That is the document to read before writing anything, because it defines the process the README summarises.

## Where this model gets in the way

The single-entry index is the most concrete limitation. A specification repository with one RFC has not yet demonstrated that the process produces proposals at a useful rate, and the README's own list of governed surfaces is much longer than the index. You are adopting a governance structure whose throughput is unproven.

The consensus step is undefined. The README says a maintainer assigns the number when consensus is reached, but it does not say who counts as a participant, how disagreement is resolved, or what happens when a proposal is technically sound and no one engages with it. For a contract surface where implementations must conform, that is a real gap: a proposal can sit in Draft indefinitely without being rejected.

The lifecycle also leaves supersession underspecified. Superseded is listed as a state and the header is supposed to note the replacement, but the README does not describe what happens to the SDK feature flag or to code already built against the superseded types. For a repository whose whole premise is that implementations follow the text, the migration path from one text to its replacement is the part you would most want documented.

Finally, this is the wrong tool for anything that is not a contract change. Bug fixes, internal refactors, performance work that does not alter an interface, and capsule implementations that consume existing standards all fall outside the list. Writing an RFC for those wastes the reviewers' time and yours.

## How it differs from a conventional RFC series

The obvious comparison is the IETF RFC series, which is where the term and much of its cultural weight come from. The differences are structural rather than stylistic.

IETF documents are produced by working groups with charters, editors, formal last-call periods, and a review by the Internet Engineering Steering Group before publication. Numbers are assigned from a global registry that spans thousands of documents, and a published RFC is immutable, with errata handled separately. The astrid-runtime repository has none of that apparatus. There is one template, one pull request thread, and a maintainer who assigns the next sequential number when consensus appears. Numbers are local to this repository and start at 0001.

The second difference is what the document is for. An IETF RFC specifies a protocol that many independent implementations may adopt. These RFCs specify an internal contract between one kernel and its user-space, with a single SDK as the delivery vehicle. That makes them closer to an architecture decision record with a formal lifecycle than to an interoperability standard. The feature-flag mapping is the clearest expression of this: the specification ships as types in one specific crate, not as a document other vendors implement against.

If you want the IETF model, this is not it. If you want a lightweight, versioned, reviewable record of why the host ABI looks the way it does, the shape here is reasonable.

## Maintenance, licensing and what to check before relying on it

The repository is not archived, and the last push was on 2026-08-10. That is recent enough that the project is not dormant, but there is no release history, so there is no versioned snapshot of the specification to depend on. You track the default branch, main.

Licensing is dual: the README states the project is dual-licensed under MIT and Apache 2.0, and both LICENSE-MIT and LICENSE-APACHE are present at the top level. The badge in the README points at the MIT file. Copyright is attributed to Joshua J. Bouw and Unicity Labs, 2025-2026. Dual licensing of this kind is common in Rust-adjacent projects and lets a consumer choose either licence, but the README does not state which licence applies to contributions you submit, and it does not mention a contributor licence agreement or a developer certificate of origin. If you plan to contribute text that others will build against, confirm the contribution terms with the maintainers before you invest in a long proposal. That is a question for them, not a conclusion you can draw from the repository listing.

The upgrade cost sits on the consumer side. Because RFC types are gated behind feature flags in astrid-sdk, a change to a Final RFC arrives as a new RFC plus a new flag rather than as an edit. Your dependency line names the flags you use, so the work of adopting a revised contract is visible in your Cargo manifest. The repository layout also includes book.toml and generate-book.py, which suggests the text directory is rendered into a book, though the README does not describe that pipeline or where the output is published. Treat the generated book as unverified until you find its destination.

## Conclusion

Adopt this repository as a reading and writing habit if you are changing anything on Astrid's contract surface: the host ABI in astrid-sys, IPC topic conventions, capability token semantics, Capsule.toml schema, VFS resolution rules, capsule interface standards, or the astrid-sdk public API. Do not treat it as a package to install, and do not expect a support forum; the process runs entirely through pull requests against text/0000-my-feature.md. Before you write anything, read 0000-template.md and text/0001-rfc-process.md, because the template and the existing process RFC define the shape your proposal has to take. If your change does not touch one of the listed surfaces, you do not need an RFC at all.

## FAQ

### What does RFC mean in astrid-runtime/rfcs?

It stands for request for comments, and in this repository it means a design proposal for a change to Astrid's kernel-to-user-space contract. The README describes RFCs as the authoritative specification, with implementations conforming to them rather than the other way around.

### Are the RFCs in astrid-runtime/rfcs mandatory standards?

Within Astrid they function as binding for the surfaces they cover. The README states that RFCs govern any substantial change to the contract surface between the kernel and user-space, and that implementations conform to the specification rather than defining it. They are not external standards that other projects are obliged to follow.

### What does RFC stand for in the IT industry, and does that apply here?

The abbreviation is request for comments, a term inherited from the IETF document series. This repository borrows the name and the idea of a numbered, reviewable proposal, but the process is a pull request against 0000-template.md with a maintainer assigning the next sequential number, not a working-group publication.

### What are RFC standards in the context of astrid-runtime/rfcs?

Here the standards are the merged documents under text/ that fix the host ABI, IPC protocol, capability model, manifest schema, VFS semantics, capsule interface standards and the astrid-sdk public API. Once an RFC reaches Final, breaking changes to it require a new RFC.

## Sources

- [astrid-runtime/rfcs on GitHub](https://github.com/astrid-runtime/rfcs)
- [Issues](https://github.com/astrid-runtime/rfcs/issues)
- [License: Apache-2.0](https://github.com/astrid-runtime/rfcs/blob/main/LICENSE)
- [README](https://github.com/astrid-runtime/rfcs/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/astrid-runtime-rfcs