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 — switch directories and 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 stale.

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

What the driver does with the handoff — mount order, longest-prefix dispatch, the fail-closed rules — is on the anatomy page; this page is about everything that happens before the interpreter starts.

Four links, 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 you 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/: the newest compatible runtime already cached wins, with no download. Only a cache miss reaches the network — the newest compatible interpreter the runtime factory released for this platform — which is SHA-256-verified against the release index before it enters the cache. Because the payload image is immutable, swapping runtimes never touches it: only this dispatch-time choice changes.

Runtimes published before the abi key existed carry no platform line, and stay eligible — the compat window: a payload’s abi check never fails against an unknown line. And an entrypoint with no runtime_requirement at all — a native tool, 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, 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>, --no-host (the tightening surface; they can only narrow what a payload’s manifest requests). Everything else, unknown flags included, reaches the payload verbatim; -- ends flag parsing for the arguments that literally are those names. On unix the shim execs — the process becomes the runtime, so 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; 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.

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: 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; TEBAKO_OFFLINE=1 turns dispatch into cache-or-named-error — a stale cache still answers offline, 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, no hidden subcommands:

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

One directory on PATH: ~/.tebako/shims. tebako-shim install-shell inserts a managed BEGIN/END block into the right startup file for your shell (.bashrc, .zshrc, ~/.config/fish/config.fish, .cshrc) — 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; on Windows an NTFS hardlink first — no admin, no Developer Mode — with a byte copy as the named fallback, never a .cmd wrapper. And there is no eval "$(… init -)" hook for switching versions: the dispatcher reads the project file itself, per invocation.

tebako press produces both. For users without tebako: the standalone per-platform tpkg executable. For dispatcher users: the registry payload — one universal image for a pure-language app, per-triplet variants only when native code forces it. 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: 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 — 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, dispatched by the shim. The whole model on this page, eaten by its own cooks.

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