ARCHITECTURE · 10

For contributors.

Onboarding into any single repo starts with the same question: which contract does this repo own, and which suite executes it? Then: how does the project notice when the world drifts?

The contract suites.

Every cross-repo claim in this architecture is backed by an executable check. When you touch a boundary, these are the suites that will judge you.

The ABI oracle — 493 tests

SHIPPED

The c_api test suite registers 493 tests under ctest and is the executable definition of tebako_fs_* behavior: errno mapping, mount semantics, dir cookies, pread position-independence, multi-mount isolation. Any change to libtfs is judged by it. In tebako-rs the ported cases run through the Rust C ABI — 164 today in tests/contract (the full sweep follows the same pattern; what was ported and why is audited in docs/parity.md), with the C++ library as the oracle.

tests/test_c_api.cpp →tebako-rs tests/contract →docs/parity.md →

Golden CLI parity — tebako-pkg & tebako-cli

SHIPPED

The Rust package tools are diffed byte-for-byte against their oracles: tebako-pkg’s bundle/info/unbundle/reassemble/insert/remove/set-runtime output must equal the released C++ tebakofs (auto-detected via TEBAKOFS_CPP, skipped without it), and tebako-cli’s lean/fat press — stdout and the packaged binaries’ output — must equal the reference gem’s in a side-by-side CI leg. A byte difference is a failed build, not a discussion.

crates/tebako-pkg →crates/tebako-cli →

The manifest schemas

SHIPPED

versions.yml is the single list of supported rubies: official URL, sha256, line, and shipped scenarios per version. Its shape is enforced by schema files, and the lint-patches matrix CI re-verifies on every change that every claimed patch still applies cleanly to the official tarball.

versions.yml →versions.schema.yml →patches.schema.yml →lint-patches.yml →

tpkg, in three languages

SHIPPED

The trailer format is owned by libtfs’s C tpkg.h and vendored verbatim into tebako-bootstrap — the vendoring is documented and checked, not improvised. tebako-rs’s crates/tpkg is byte-exact with it (golden vectors asserted offset-by-offset) and carries the v2 chain-of-trust extension; v2 is flagged, not version-bumped, so v1 readers parse on untouched. Changing the format means moving all sides in the same breath.

VENDORED.md →crates/tpkg →

The launcher ABI, in two languages

SHIPPED

The gem’s launcher_abi.rb carries the Ruby-side constants of the bootstrap→runtime handoff, with matching C++ constants in the runtime entry driver. The file itself warns: keep the two in sync, and bump VERSION on any incompatible change. The additive ;image runtime_ref flag (runtime as image) is the standing example of evolving the handoff WITHOUT a bump.

launcher_abi.rb →

How drift is detected.

SHIPPED

Ruby upstream moves constantly; tebako's patches are pinned to exact tarballs. The release monitor runs on a daily cron in tamatebako/ruby and closes most of that gap unattended:

daily cron
  1. detect    diff official ruby-lang.org releases against versions.yml
  2. onboard   add to versions.yml → select patch set → git apply --check each patch
  3a. clean    PR/commit → tag → release-src publishes tfs-ruby-<v>-src-*.tar.gz
               → repository_dispatch tebako-runtime-ruby to build the runtime
  3b. drift    any patch failing → open a named issue (version + failing patch)
               — never a silent bad release

The open issues in tamatebako/ruby are the live example: each "Onboard ruby X.Y.Z: patches fail to apply" issue is the monitor naming a version whose upstream changes broke a patch.

How drift gets fixed.

PLANNED

Detection is shipped; the closure loop is the designed next step. A drift-update flow picks a drift issue, forks or updates the named patch for that version, re-verifies with git apply --check, and lands it via PR — on merge the version onboards (src publish + runtime build) and the issue closes. Each drifted version ends with either an updated patch or an explicit wontfix recorded on its issue. This is the most mechanical — and most welcome — first contribution to the ecosystem.

Where to run the checks.

libtfs

Platform CI on ubuntu/alpine/macos/windows plus verify-no-folly and test-static-linking — and the 493-test ctest suite as the ABI gate.

tamatebako/ruby

The lint-patches matrix (every version in versions.yml) proves each patch applies to its official tarball; release-src verifies published trees match apply-output byte-for-byte.

tebako-runtime-ruby

The build-runtime-packages matrix (19 rubies × platforms) builds from patched source; release assembly publishes manifest.json + SHA256SUMS.

tebako-bootstrap

self-test.sh stitches a lean package from a freshly built launcher and a fake runtime, then exercises the download, cache-hit, offline, checksum-mismatch, and ABI-mismatch paths.

tebako-rs

CI runs the workspace tests on ubuntu-24.04 + macos-14 (vendored vcpkg baseline pinned, archive cache keyed on both manifests) plus a pure-cargo --no-default-features leg, the golden-parity legs against the C++ oracles, and the bootstrap size gate — per-platform sizes published, failing at ≥ 3 MB.