ARCHITECTURE · 07
The Rust track.
What was the locked future is now the shipped present: the tebako-rs workspace exists, and every crate in it is code-complete and parity-verified against the C++ oracle. The remaining "planned" is distribution, not implementation.
Why Rust, and why a new repo.
The bootstrap runs before Ruby and touches trailer bytes, the filesystem, the network, and exec — memory safety pays off exactly there. A single static CLI removes the bootstrap paradox (needing a Ruby to package Ruby) and dogfoods the single-binary philosophy. And a fresh workspace got clean history, Rust-native CI (cargo, no vcpkg in the consumer path), and a release cadence decoupled from the C repos until parity — which is exactly how it played out.
The workspace, crate by crate.
The manifest format — parse/serialize/validate/crc32, byte-exact with the reference C tpkg.h (golden vectors asserted offset-by-offset). Carries the v2 chain-of-trust extension: per-slot sha256 array + signer keyid + OpenPGP signature block, flagged (not version-bumped) so v1 readers parse on untouched.
PARITY PROOF — Golden vectors generated by the C implementation; proptest round-trips; error codes/strings 1:1 with TPKG_ERR_*.
libtfs-rs: the tebako_fs_* ABI as a cdylib/staticlib drop-in (libtfs.so/.dylib/.dll/.a). Mount table, fd/dir tables, longest-prefix dispatch, errno channel; zip (pure-Rust), dwarfs (via dwarfs-t-rs) and squashfs (via sqfs-sys) backends; multi-mount with unmount-by-handle; the full io surface incl. pread, dir cookies, dlmap2file.
PARITY PROOF — Exactly 33 tebako_* exports, nm-verified — the 24-function contract surface plus tebako_fs_abi_version and 8 compat/introspection helpers; nothing else leaks. 164 contract tests ported from the C++ suite run through the Rust C ABI.
The package surgery CLI, scoped to tpkg trailer operations: bundle / unbundle / reassemble / insert-image / remove-image / set-runtime / info. bundle --sign[=keyid] adds the v2 signature; rewrites preserve the input’s signing state.
PARITY PROOF — Golden byte-parity with the released C++ tebakofs: bundle output, info output, manifest.json, unbundled parts, reassemble round-trip, atomic rewrites — byte-identical (oracle auto-detected via TEBAKOFS_CPP; skips without it).
The tfs binary — the generic VFS image tool (tfs : libtfs :: sqlite3 : libsqlite3), not tebako-specific: info (--json backend metadata), ls/ls -r/ls -l, tree, cat (pread-chunked), stat, extract (mtime-preserving), find, mkimage.
PARITY PROOF — Exact C++ tebakofs output/exit-code/stream-split parity, verified against the oracle binary. serve / shell / exec modes: planned.
The Rust bootstrap runner — a port of the C99 v0.2.0 contract: trailer parse, ABI check, runtime_ref parse (incl. the ;image flag), cache hit / fat payload / lean download, per-entry locks, atomic installs, the v1 exec handoff, and v2 signature + per-slot sha256 verification.
PARITY PROOF — The ten self-test.sh scenarios ported as integration tests plus a direct parity run against the C++ oracle binary; named exit codes 65–74 incl. the new 71/72. Size gate below.
The tebako packager CLI — item 17’s self-hosting design: lean/fat press, cache list/prune. Resolves runtimes into the gem-identical ~/.tebako cache, deploys the app under the downloaded runtime itself (bundler invoked, never reimplemented), images in-process via the dwarfs-t Writer, stitches the three-part package. Emits ;image refs against image-era releases.
PARITY PROOF — Golden byte-parity vs the reference gem: same fixture, same prefix — press stdout and the packaged binaries’ output byte-identical (CI diffs side-by-side). Documented deviations: RuntimeSdk/src-release subsystem, classic mode, gem/gemspec scenarios, .tebako.yml not yet ported.
In-process HTTPS downloads shared by the CLI and the bootstrap: ureq + rustls (ring) with webpki-roots bundled, HTTPS-only, redirects ≤ 5, file:// mirrors, OS trust store opt-in via TEBAKO_TLS_PLATFORM_ROOTS. No curl anywhere — the C++ bootstrap’s last shell-out is gone.
PARITY PROOF — Retry parity kept (transient ×3, 404 fast); cost measured: +867 KB of TLS stack in the bootstrap artifact.
The OpenPGP half of the chain of trust — rnp-rs over librnp, #![forbid(unsafe_code)]. Press-local Ed25519 key under $TEBAKO_HOME/keys, trusted keyring with TOFU registration, detached sign/verify classifying Trusted / Untrusted / Invalid.
PARITY PROOF — Feeds tebako-pkg --sign and the bootstrap’s first-run verification (exits 71/72).
Hand-written FFI to libsquashfs (squashfs-tools-ng), same discipline as dwarfs-t-sys: ~15 externs pinned by abi_check.c _Static_asserts, a C-side shim for the variable-layout compressor config, a Rust-side memory-backed sqfs_file_t. POSIX-only — same restriction as the C++ side.
PARITY PROOF — Same vcpkg overlay port (1.3.2) on both sides of the parity gate — version parity, not just API parity.
Beside the workspace: dwarfs-t-rs, the standalone Rust binding to dwarfs-t — safe dwarfs-t crate (reader + in-process Writer) over the hand-pinned 22-function dwarfs_c_* C ABI. Not tebako-specific, crates.io-bound, tracking dwarfs-t releases. dwarfs-t itself stays C++ forever; the C ABI is the only Rust-consumable surface.
How parity is proven.
tebako_fs_* and tpkg are byte-level contracts, so the tests come from the C++ side and run unchanged against the Rust implementation: the c_api cases ported against the same fixtures with the same errno expectations (164 tests in tests/contract today — the audit of what was ported and why is docs/parity.md; the full 493-case sweep follows the same pattern), tpkg golden vectors produced by the reference C implementation, tebako-pkg/tebako-cli golden runs diffed byte-for-byte against the released C++ tools, and the exports checked with nm. A mismatch means the contract moved — and both sides must move together.
The bootstrap size gate — an honest history.
SHIPPED · gate: < 3 MBThe bootstrap ships inside every package, so its size is a hard CI gate, not a nice-to-have. The budget moved as the feature set did — and the moves are recorded, not swept under:
| STAGE | GATE | MEASURED |
|---|---|---|
| Original design budget | ≤ C++ baseline + 512 KB, ≤ 1 MB | C++ v0.2.0 baseline: 32,512–908,112 B |
| M6 — runner ships (curl downloads) | < 2 MB | 371,776 B (macOS arm64) |
| M7a — downloads go in-process (tebako-http) | < 3 MB — owner-raised when curl was dropped | 1,238,384 B macOS arm64 · 1,664,336 B ubuntu (+867 KB TLS stack) |
The discipline stands: opt-level="z", fat LTO, one codegen unit, panic=abort, stripped symbols; no async runtime, no clap. CI publishes the per-platform size table on every run and fails at ≥ 3 MB. The C++ bootstrap remains the released default until the tebako-rs release pipeline ships — no size regression is ever forced on tpkg users. Windows exec/lock ports land with the Windows CI leg (v1 shipped macOS/Linux).
What is still planned.
PLANNED- The tebako-rs release pipeline — signed per-platform binaries (tebako-bootstrap, tfs, tebako-pkg, tebako-cli) with the size table, SHA256SUMS and a manifest.json in the shape the existing resolution code already consumes. This is the distribution channel everything above waits on.
- crates.io publication of tpkg/tfs (after the API settles), with the cbindgen tpkg.h; dwarfs-t-rs tags + cargo publish + docs.rs.
- tebako-cli remainder — classic press mode, gem/gemspec scenarios, the RuntimeSdk/src-release subsystem (native-extension deploy), .tebako.yml.
- tfs-cli serve/shell/exec modes and the tfs-fuse driver — the "advanced FUSE without OS integration" matrix.
- tebako-shim — the version-manager dispatcher crate (see the version manager page).