ARCHITECTURE · 08
Repository map & lifecycle.
The stack is a fleet of small repos, each owning one artifact and one contract. None of them is disposable by default — archival is an end state with explicit gates, never a starting move.
| REPO | ROLE | STATE | FATE |
|---|---|---|---|
| dwarfs-t | Thrift-free DwarFS fork — the high-compression read-only filesystem at the bottom of the stack, plus the dwarfs_c_* C ABI (writer included) that Rust binds. | Active | C++ forever by decision (it tracks upstream DwarFS format evolution). Never archived — the foundation, not a legacy repo. |
| dwarfs-t-rs | Standalone Rust binding to dwarfs-t: the safe dwarfs-t crate (reader + in-process Writer) over dwarfs-t-sys’s hand-pinned FFI. Consumed by tebako-rs as an ordinary external dependency. | Active | Active forever — general-purpose, crates.io-bound (tags + cargo publish + docs.rs when it publishes). Never inside tebako-rs. |
| libtfs | The C++ VFS engine: tebako_fs_* C ABI (24 exports, multi-mount), dwarfs/squashfs/zip backends, mkdwarfs + tebakofs binaries. Currently v0.13.0 — the parity oracle for the Rust tfs crate. | Active (oracle) | Maintenance (security/critical fixes only) once tebako-rs ships tebako_fs_* parity RELEASES AND tebako-runtime-ruby consumes them — the tfs crate is at parity in the workspace; the releases are the pending step. Archival gate below. |
| tebako-rs | The Rust workspace: tpkg, tfs, tebako-pkg, tfs-cli, tebako-cli, tebako-bootstrap, tebako-http, tebako-signer, sqfs-sys — all shipped and oracle-verified. No downloadable releases yet. | Active | The future home of the CLI, the ABI implementation, the bootstrap, and the shim. Release pipeline (signed per-platform binaries) is the open item. |
| ruby | Canonical patches + versions.yml + the patched-source pipeline (release monitor, lint matrix, release-src). Currently v0.2.1 — 76 scenario assets. | Active | Never archived — build/metadata tooling, language-correct as-is (not C++). |
| tebako-runtime-ruby | The runtime factory: builds patched source per ruby × platform, publishes runtime packages + manifest.json. Currently v0.15.9 — 114 packages; dual-publish of .tfs runtime images alongside the executables is rolling out. | Active | Never archived — build/metadata tooling (not C++). |
| tebako | The gem: press (lean/fat/classic), scenario + Gemfile handling, runtime/bootstrap resolution, cache CLI. The reference implementation tebako-cli was ported against (golden byte-parity). | Maintenance-bound | Retires at 0.15.x with a deprecation note once tebako-cli ships releases (owner decision 2026-07-26: tebako-cli IS the product; a pure-Ruby installer shim may preserve the gem-install habit — an FFI wrapper was evaluated and rejected). Archival gate below. |
| tebako-bootstrap | The C99 launcher (part A of the three-part package), v0.2.0 — six platform binaries, 32–908 KB. Now the behavioral oracle for the Rust tebako-bootstrap crate. | Maintenance | Stays the released default until the tebako-rs release pipeline ships; archived only when the Rust bootstrap ships and is consumed as the bootstrap slot. |
| tebako-ci-containers | Container images the runtime matrix builds in. | Active | Never archived. |
| tebako-samples | Sample applications and packaging tutorials. | Active | Never archived. |
| tebako.org | This website. | Active | Never archived. |
| fmem | Cross-platform memory-backed libc streams — a dependency of the legacy stack. | Orphaned | The archival candidate: no longer consumed by any repo in the modern stack (libtfs mounts images from memory directly). Still not archived on GitHub as of this writing — it goes when the owners pull the trigger, not before. |
Archival gates.
A repo is archived only when its gate is fully met — existing released artifacts must remain reproducible until every consumer has migrated off them. Three repos carry gates; the rest are either permanent foundations or not C++ at all.
libtfs (C++)
libtfs-rs parity sustained for 2 consecutive releases + tebako-runtime-ruby pinned to tebako-rs + the gem/CLI fully off C-libtfs. Progress: the tfs crate is at parity in the workspace — the releases do not exist yet.
tebako (gem)
tebako-cli press parity (lean/fat/classic) green end-to-end on 3 platforms + one full release cycle of dual availability. Progress: golden byte-parity for lean/fat is proven in CI; classic mode and the tebako-rs releases are pending.
tebako-bootstrap
Only if a Rust bootstrap ships and is consumed by tebako-pkg/tebako-cli as the bootstrap slot. Progress: the Rust bootstrap is behavior-complete and size-gated in the workspace; tebako-cli already defaults to it in-workspace — consumption via released binaries is the pending step.
The lifecycle rules.
Contracts outlive implementations
The tebako_fs_* ABI and the tpkg trailer are byte-level contracts. Consumers don't care which repo ships them — that's what made the Rust reimplementation possible without flag days, and the C++ side now serves as the parity oracle for exactly that reason.
Releases are the interface
Repos consume each other's published releases, never source trees. The gem and the runtime factory live in different repos with separate cadences — the manifest.json contract sits between them, so the packager never hardcodes a runtime matrix.
Maintenance mode is a state, not a graveyard
A maintenance-mode repo still gets security and critical fixes. It stops getting features — and it leaves maintenance mode if its replacement slips. The C++ bootstrap is exactly here: released default, oracle for its Rust successor.
dwarfs-t is not legacy
A Rust DwarFS reader/writer is explicitly out of scope. The only Rust-consumable surface is the C API inside dwarfs-t itself, co-versioned with the C++ it wraps — which is what dwarfs-t-rs binds.