Specification
This section is the behavioural specification of FlatRoot: one page per use case, each recording what the tool promises for that request and how the promise travels through the system's packages. The pages are contracts, not tutorials — for hands-on instructions see the How-To guides, and for the meaning of each package see Packages.
Every page follows the same spec shape: a status header (these are as-built specs — the code is the source of truth, so there are no open clarifications), User Scenarios & Testing with user stories, each independently testable and carrying Given/When/Then acceptance scenarios, then the atomized functional requirements — grouped by concern under bold group headers, each requirement a normative MUST statement identified as FR-<GROUP>-NNN and followed by a concrete annotated example of the behaviour it pins (every guarantee and every deliberate refusal) — the key entities the use case reads or produces, measurable success criteria (SC-###), the assumptions the request relies on, and the edge cases with their settled answers. Identifiers are page-scoped: FR-SOURCE-001 on one page is unrelated to FR-SOURCE-001 on another; cite them as page + ID. A requirement group describing behaviour that is specified but not yet implemented is explicitly marked (proposed — not yet built), and the page's status header names it.
One deliberate departure from a to-be-built spec: each page closes with an Execution flow (as-built) section — the ordered operations table (each step naming the package that performs it and the source that implements it) and the package-level sequence diagram. A prescriptive spec would exile that material to a separate plan document; here it is the trace that binds every requirement back to the architecture, which is this spec's purpose.
Use cases
| Use case | Trigger | Outcome |
|---|---|---|
| Installing Packages | install |
A usable rootfs directory holding the requested packages and their closure, with a truthful install record |
| Searching Packages | search |
The packages or libraries matching the given patterns, with enough detail to act on each hit |
| Querying the Catalogue | query |
The result rows of a free-form SQL question posed against the local package catalogue |
| Listing Distributions | remote list |
The roster of buildable distributions and the selector syntax each accepts |
| Listing Releases | release list |
The releases a chosen distribution currently offers, validated as genuinely installable |
| Exporting a Rootfs | export |
A finished rootfs sealed into one portable artefact — archive, container image, or mountable filesystem |
| Tracing Dependencies | analyze trace |
The classified dependency closure of a set of seeds — declared edges, real linker edges, and the gaps between them |
Diagram participants
The sequence diagrams speak one fixed vocabulary: every participant is a package from the Packages page, under the short alias below. Participants appear in a diagram only when the use case actually flows through them.
| Participant | Package | Source |
|---|---|---|
Entry |
Command-Line Entry and Dispatch | src/main.rs, src/parser.rs, src/executor.rs |
Command |
Subcommand Orchestration | src/commands/ |
Distro |
Distribution Catalog | src/distro/ |
Remote |
Format-Neutral Repository Access | src/remote/ |
Mirror |
Network Source and Mirror Fallback | src/mirror/ |
Format |
Package-Format Parsing and Extraction | src/pkg/ |
Catalogue |
Persistent Package Catalogue | src/db.rs |
Resolver |
Dependency Closure Resolution | src/resolver/ |
Graph |
Dependency Graph Assembly | src/dep_tree.rs |
Download |
Verified Parallel Download | src/downloader.rs |
Inspect |
Binary and System Inspection | src/elf.rs, src/arch.rs, src/library.rs, src/path.rs, src/path_index.rs |
Record |
Rootfs Build Record | src/manifest/ |
Sandbox |
Unprivileged Execution Sandbox | src/sandbox.rs |
Postinstall |
Post-Install Finishing | src/postinstall/ |
Repair |
Final Permission Repair | src/postfixes/ |
Utility |
Generic Utility Tier | src/internal/ |
Upstream |
The distribution's mirror servers — external to FlatRoot, shown where bytes actually leave the machine | — |
Two conventions keep the diagrams readable. First, they show control and data flow between packages, not type reuse — a package that merely imports another's value types (the Package Vocabulary, the version comparators, the integrity claim) is credited in the operations table instead. Second, the cross-cutting packages every flow leans on — User-Facing Progress Output and most of the Generic Utility Tier — are omitted unless a flow's substance genuinely runs through them, as it does for export.
Related pages
- Architecture / Spec / Exporting a Rootfs — A user names a finished rootfs and a destination and receives one compressed archive any ordinary tool can unpack — reproducible, faithful to symlinks, and free of the...
architecture spec export - Architecture / Spec / Installing Packages — A user names a distribution, a release, a destination directory, and the packages they care about, and receives a complete root filesystem: the requested packages, everything...
architecture spec install - Architecture / Spec / Listing Distributions — A user asks which distributions are even an option and exactly how to ask for one, and receives the complete roster — each entry with the selector syntax it documents —...
architecture spec remote