Dispatch.

A lean tebako package already is a dispatcher: it resolves its runtime at run time. Managed mode splits that trick into four independent artifacts, each with its own publisher, its own release line, and its own trust anchor.

Nothing is sticky. Every invocation of a shim walks the whole chain again, and a directory switch means the same command can resolve to a different version on a different runtime. That is the mise model: the project file is read at dispatch time, so there is nothing to activate and no shell state to go stale.

Figure 1 — The dispatch cascade: invocation name, version chain, runtime resolution, the exec handoff, and the interpreter running.

The driver’s treatment of the handoff, the mount order, longest-prefix dispatch, and the fail-closed rules, is on the anatomy page; this page covers everything that happens before the interpreter starts.

Four links are evaluated in order; the first link that names a version wins, and later links are not consulted.

If no link answers, the error says so, listing every link it tried and the versions actually installed (exit 69). A resolved version that is not installed, or that the user disabled, is likewise a named refusal with the remedy in the message. Dispatch never guesses a version.

The chosen entrypoint’s runtime_requirement (an engine plus a version constraint) is evaluated against ~/.tebako/runtimes/, and the newest compatible runtime already cached wins, with no download. Only a cache miss reaches the network, which fetches the newest compatible interpreter the runtime factory released for this platform; that interpreter is SHA-256-verified against the release index before it enters the cache. Because the payload image is immutable, swapping runtimes never touches it, and only this dispatch-time choice changes.

Runtimes published before the abi key existed carry no platform line and stay eligible; this is the compat window, in which a payload’s abi check never fails against an unknown line. An entrypoint with no runtime_requirement at all, a native tool or a self-contained binary, skips this entire section: zero-runtime dispatch runs the install-time materialization straight from the store, with no runtime mounted and no VFS in the child.

One exec speaks one wire format, the same launcher ABI the standalone bootstrap speaks. The registry payload is a bare image, so it mounts whole: slot 0, mount point /. Dependency slices follow at their consumer-declared mount points.

Environment on top of the inherited one: TEBAKO_RUNTIME_IMAGE names the env image the driver mounts at the runtime root; when a jail policy applies, TEBAKO_JAIL carries it, with TEBAKO_JAIL_SOURCE and TEBAKO_JAIL_JOURNAL for the audit trail.

The shim consumes exactly three flags before handing over: --jail <spec>, --mount <host:mount:ro|rw>, and --no-host, which form the tightening surface and can only narrow what a payload’s manifest requests. Everything else, unknown flags included, reaches the payload verbatim, and -- ends flag parsing for arguments that literally carry those names. On unix the shim execs, so the process becomes the runtime and signals and the exit code are the program’s own; on Windows it spawns, waits, and exits with the child’s code.

A registry is any git-host repository carrying a tpkg-registry.yaml, and the host’s releases are the artifact storage. The file mirrors only resolution-relevant fields (versions, per-triplet artifacts with SHA-256 digests, runtime_requirement, entrypoints, default:), so the dispatcher resolves without downloading every payload. Platform selection happens in the file, declaratively: the dispatcher reads the entry for the host triplet (or universal) and fetches exactly that artifact. Nothing guesses by filename.

Registry use is explicit only: a fresh install of tebako has zero registries. tebako add-registry <ref> registers one; there is no default registry, no central index, and no search chain. Each reference form resolves in exactly one place (the repo’s default-branch root via the contents API, a pinned release artifact, a git blob path, or a local file://), and an unparseable reference is a named error, never a guess.

The dispatch cache is the second property: remote registries use a per-reference cache under ~/.tebako/registries/<sha256-of-ref>.yaml with a 24-hour TTL, so dispatch never blocks on the network twice in a row. tebako update-registries renews it ahead of time, tebako add-registry primes it with the bytes it already fetched, and TEBAKO_OFFLINE=1 turns dispatch into cache-or-named-error, in which a stale cache still answers offline and a missing one fails by name.

Install is the explicit verb: tebako install <name[@ver] | ref> resolves the registry, selects the host entry, downloads, verifies (SHA-256 and/or the OpenPGP signature), and lands the payload byte-identical in the content-addressed cache, then registers the payload’s shims. Registry installs always link the declared entrypoints; installing a local package file links only with the explicit --shims; a run, of anything, ever, links nothing.

Invoked by its own name, the same binary is the management tool. This is the whole surface: there is no tebako use, no tebako shim add, and no hidden subcommands:

Disable state lives in ~/.tebako/shims/.disabled.yaml, shim-managed and deliberately separate from the user’s authored config.yaml, so disable never rewrites a hand-maintained file. doctor is the diagnostic path that the error messages point at: it re-hashes payload images against their install-time trust anchors and exits 1 when anything is wrong.

Shell integration is one directory on PATH: ~/.tebako/shims. tebako-shim install-shell inserts a managed BEGIN/END block into the right startup file for the user’s shell (.bashrc, .zshrc, ~/.config/fish/config.fish, .cshrc); it is idempotent, and uninstall-shell removes exactly its block. On Windows the shim directory goes onto the user PATH in the registry instead. The links themselves are the platform’s own: symlinks on unix, and on Windows an NTFS hardlink first (no admin and no Developer Mode) with a byte copy as the named fallback, never a .cmd wrapper. There is also no eval "$(… init -)" hook for switching versions, because the dispatcher reads the project file itself, per invocation.

tebako press produces both forms. For users without tebako, the form is the standalone per-platform tpkg executable; for dispatcher users, it is the registry payload, one universal image for a pure-language app with per-triplet variants only when native code forces them. The release flow is press → sign → upload the artifacts → commit the registry manifest, and tebako publish automates it for GitHub releases and file:// mirrors. Building every variant is a matrix CI job, not manual work.

The dispatcher reuses the loader’s named exit set rather than inventing its own. The dispatch-specific truth behind the table is that a native-extension payload on a wrong-ABI-line runtime is exit 69 with both lines named, never a segfault.

Once the interpreter is running, exit codes are the program’s, because the shim is out of the picture by then.

With tebako-shim shipped, mnenv — metanorma’s Ruby version manager — retires, and metanorma becomes the first dogfood consumer of this exact chain: a heavy native-extension app, pressed per (version × ruby line), published through its own registry, and dispatched by the shim. The whole model on this page is thus exercised by the very project it serves.

See also: Shims and versions · Where everything lives · The runtime as an image.