Skip to content
All posts
3 min readtebakoarchitecturepackaging

Architecture: The three-part package (1 of 5)

The tebako v2 model in five concepts: the three-part package, the runtime as an image, composition, the host boundary, and trust.

The Tebako team

github.com/tamatebako
Note

Post 1 of 5 in the series Tebako v2 architecture.

● ○ ○ ○ ○

  1. Architecture: The three-part package (this post)

  2. Architecture: The runtime as an image

  3. Architecture: Composition

  4. Architecture: The host boundary

  5. Architecture: Trust and the release chain

This series describes how tebako v2 works — one concept per post. This first post covers the model everything else builds on: what a tebako package is made of.

A tebako package is an executable built from three kinds of parts, and each part does exactly one job:

  1. The bootstrap — a small Rust loader, under 3 MB. It is the entry point of every package: it reads the package trailer, finds the runtime, verifies it, and hands control over. It never runs the application’s code itself.

  2. The runtime — the language interpreter the application needs. It ships as two artifacts — the interpreter executable, and an environment image holding the standard library and gems. The next post covers it in full.

  3. Payload slices — the application, its data, and the tools it needs, each a disk image that describes itself with a manifest inside the image.

Anatomy of a package the package — one file bootstrap under 3 MB, Rust slot 1 metanorma .tfs slot 2 inkscape .tfs trailer runtime ref + mounts at run time the runtime interpreter exe + env image, shared from ~/.tebako the slices mounted in memory, never extracted one process the bootstrap read the trailer, resolved the runtime, verified it, and mounted each slice at its declared path your program runs the same bytes on every machine — the store never re-stitches or patches a payload

Figure 1 — The file contains a small bootstrap, numbered payload slots, and a trailer that names the runtime and the mounts; at run time the parts co-mount in one process.

What holds the parts together

The composition is recorded in a small trailer — 166 bytes plus one record per slot — at the end of an otherwise ordinary file. The trailer names the runtime the package needs and lists the slices stitched into the executable.

Because the parts are glued at the end of a normal file, a tebako package stays a normal file: it can be fetched with curl, made executable with chmod, shipped in a tarball, notarized, or hardlinked into a Chocolatey package.

Carried or shared

Every slice is one of two kinds, and the choice is made when the package is pressed:

  • Carried — the slice’s bytes are inside the executable, so the distribution is one file that includes everything.

  • Shared — the executable names the slice, and the slice resolves from a registry into the machine’s store on first use. Runtimes always work this way; toolkits can too.

Carry changes where the bytes come from, never what runs: the mounted result is identical either way.

Where this series goes

The next four posts cover each part of the model in depth: the runtime as an image, the composition grammar, the host boundary, and trust. The basic payloads series runs the whole model hands-on for readers who prefer to start by doing.

Note

Continue with part 2 of 5: The runtime as an image.