The VFS model.

The product line is three things: libtfs, the engine, spoken through the tebako_fs_* C ABI; the tfs CLI, the human surface (tfs : libtfs :: sqlite3 : libsqlite3); and tebako-pkg, which does tpkg trailer surgery, a tebako concept rather than a TFS one. The ABI is additive-only (tebako_fs_abi_version() = 1), and exactly the tebako_* symbols are exported, nm-verified, with nothing else leaking.

Calls reach the router in three ways. The packaged interpreter’s patched IO calls the ABI in-process: open, pread, stat, opendir, and friends. Native executables get the VFS injected through the preload interposition shim (tfs exec), which is itself a TFS consumer. A dlopen of a VFS-resident library materializes the file to the exec cache first (tebako_fs_dlmap2file), so the OS loader maps a real file. Everything else, the working directory, writes outside held trees, mkdir, and unlink, goes to the host, policy-gated.

One process can attach many images at once: the env image at the runtime root, the app payload, and data payloads. Each mount gets a monotonic handle (never reused) and its own backend instance; there is no global mount state, which is what makes N concurrent mounts safe. Path resolution is longest-prefix dispatch on component boundaries: nested mounts shadow outer ones, and a duplicate mount point is refused with EEXIST. Every fd and dir handle records its owning mount, so unmounting one image force-closes only its own handles (later use fails EBADF) and leaves the rest fully usable.

Figure 1 — The TFS router: longest-prefix dispatch onto read-only backends, with the COW and ENC transforms stacked above; everything else passes through to the host filesystem.

Symlinks play by the router rules too: relative targets resolve inside their own mount and never escape it, and absolute targets resolve through the mount table, so a link in one payload can land in another; cross-mount links work, and that is the point of composition. A target outside every mount is host-passthrough under the same jail policy as any host path, so a symlink can never widen a jail.

A mount covers everything under its mount point, but its image holds only the entries it actually contains. A covered path the image does not hold does not surface the backend’s ENOENT; open, stat, and opendir fall through to the host answer, gated by the jail policy. With the app payload mounted at /, the v2 dispatch shape, this is exactly what keeps the host filesystem reachable: held content serves from the image (read-only), and everything else behaves as if no mount claimed it.

Backends are pluggable drivers behind one trait, and new formats are additive. The capability model is honest per format, with no uniform read/write pretense. Runtime mounts are read-only by default (TEBAKO_MOUNT_RO); TEBAKO_MOUNT_COW stacks the composite transform, and TEBAKO_MOUNT_RW is ENOTSUP, because backends never learn to write.

Format detection keys on bytes, not on the trailer: strong magic first (zip PK\x03\x04, dwarfs, squashfs hsqs, limnifs LMFS), with the weak tar heuristic always last. The trailer’s format_id is a hint and answers exactly one question, how to read these bytes: 0 auto, 1 dwarfs, 2 squashfs, 3 zip, 5 limnifs. Id 4 stays the legacy runtime-role wart, never mounted and never reused. Runtime-role and entrypoint semantics live in the manifest, never in the format axis. A mount whose detected format has no compiled-in backend fails with the named ENOTSUP, never a silent re-route and never a partial read.

Transforms are not formats: they stack above a backend, and they exist only in the Rust TFS. The stack order is pinned: COW → ENC → format backend. COW is always outermost, and ENC decrypts exactly one image’s backend and sits underneath.

TFS is self-similar: images are files, and any file is mountable. Three mount sources are shipped: a host file, a file region (offset + length, which is how a package slot mounts without extraction), and memory. The fourth, the VFS-file-region, mounting an image addressed by a path inside an existing mount, with the new backend reading its bytes through the owning mount’s pread, is specified as the encapsulation primitive ("an FS includes another FS at a directory path") and is not yet surfaced in the C ABI. Nested mount points work today, and nested mount sources are the planned step.

Six ways to get at image contents exist, ordered by transparency. Each one is honest about what it costs and where it runs.

One logging facility, tebako-log, serves the whole system, with every component wired through it; there is no ad-hoc eprintln! anywhere in the stack. Three environment variables control it:

The discipline is zero cost when off: the config is read once, and the gate runs before any formatting. Paths, decisions, and digests are loggable, while payload contents and key material never are.

See also: The anatomy of a package · Running binaries from images · Where the images live