The feature surface.

A payload is not a blob — it is a self-describing artifact. Every .tfs image carries its own manifest at a well-known path inside the image, /__tpkg__/manifest.yaml, and any consumer — bootstrap, dispatcher, tfs CLI, a foreign project — reads it through TFS itself. No sidecars, no central service. YAML is the locked convention for all configuration surfaces, matching versions.yml and the patch manifests. Because the manifest is integrity-bound to the image digest, it is exactly as tamper-proof as the content.

# /__tpkg__/manifest.yaml — illustrative; the locked schema
schema_version: 1
kind: app                 # app | data | toolkit | runtime | language
name: my-app
version: 1.0.0

# — provenance —
producer:  { tool: tebako-cli, tool_version: "…" }
created:   2026-07-27T00:00:00Z
source:    { app_commit: 9f3c2ab… }   # or src tarball hash / builder id
sbom:      sbom.spdx.json             # reference, inside the image

# — identity (two digests, two jobs) —
digest:
  tree_hash:   4c9e…      # plaintext merkle root — semantic identity (CAS)
  blob_sha256: 71af…      # transport identity

# — trust descriptors: optional, per part —
signing:    { state: signed, keyid: 0123…cdef, mechanism: openpgp }
encryption: { state: none }   # or per-part: { paths, algorithm, envelope_refs } — never keys

# — yours —
annotations:                # free-form k/v, OCI-style; unknown keys preserved
  org.example.homepage: https://example.org

Dependency resolution matches declared capabilities, never file guesses — the RPM Provides: / pkg-config semantics. A payload's provides is its promise of what it can do: which executables it carries, which libraries, which paths, which environment it sets. The dispatcher trusts the promise or rejects it — it never goes spelunking inside the image to find out.

# a runtime payload's promise — illustrative
provides:
  engine:   ruby
  version:  3.3.7
  abi_line: "3.3"
  platform: aarch64-macos
built_from: { src_digest: 9c37…, patch_set: v0.2.1 }
env:        { GEM_PATH: /__runtime__/lib/ruby/gems/3.3.0 }
capabilities: { exec: true, read: true, runtime: true }

Payloads declare their dependencies; the dispatcher resolves them as a graph. Three dependency kinds cover the whole space — the language engine, native toolkit layers, and shared data layers — and every node of the graph is the same signed .tfs artifact type. One coherent algebra, all the way down.

requires:
  - kind: language            # the engine (ruby today; python/julia later)
    engine: ruby
    constraint: "~> 3.3.0"    # abi-line lock (native exts)
                               # …or ">= 3.3, < 5.0" (pure ruby — a range)
  - kind: toolkit             # a native toolkit layer (gtk-layer, qt-layer)
    name: gtk-layer
    constraint: ">= 3.24, < 3.25"
    triplets: [aarch64-macos, x86_64-linux-gnu]
    mount: /__layers__/gtk    # declared by the CONSUMER (below)
  - kind: data                # a shared data layer
    name: iso-codes
    constraint: ">= 2024.1"
    mount: /__app__/share/iso-codes

Every payload carries an entrypoints array and a capabilities set. Today every package has exactly one entrypoint and runs as one command. The contract generalizes: a suite is one tpkg with N image slots and N entries — one binary, many commands, each dispatching to its own image and its own runtime requirement.

# N=1 — the simple app (today's shape)
entrypoints:
  - name: my-app
    path: /__app__/bin/my-app
    runtime_requirement: { engine: ruby, constraint: ">= 3.3, < 5.0" }
capabilities: { exec: true, read: true }

# a suite — one tpkg, N slots, N commands (planned)
entrypoints:
  - name: doc-render
    path: /__slots__/doc/bin/render
    runtime_requirement: { engine: ruby, constraint: "~> 3.3.0" }
  - name: img-render
    path: /__slots__/img/bin/render
    runtime_requirement: { engine: ruby, constraint: "~> 3.4.0" }

Capabilities are the payload's self-declaration of what consumers may do with it: exec (runnable), read (mountable for reading), runtime (usable as an engine). A data image declares { exec: false, read: true } — and the dispatcher believes it.

Every payload declares platforms as either universal — pure-ruby or data, one image for every platform — or an explicit list of canonical triplets in vcpkg form <arch>-<os>[-<abi>]. One mapping, owned by the tpkg crate, consumed identically by the dispatcher, the release tooling, and the registry:

Two distribution forms ride this axis, both produced by tebako press: the standalone tpkg (per-platform always — for users without tebako) and the registry payload (one universal .tfs when pure-ruby; per-triplet variants only for native-ext apps). See the released matrices on the runtime and libtfs release pages.

Naming note: the project-pin file started life as .tebako-tools.json in the design docs and moved to .yaml with the YAML-everywhere lock — all configuration surfaces speak YAML.

GUI apps get the same algebra as everything else: the toolkit is a layer, not a bundle. A gtk-layer is built once per triplet, published as a signed .tfs, and content-addressed — so ten GUI apps on one machine share exactly one copy. A webview variant (the app renders into the platform webview instead of a full toolkit) rides the same contract.

Metanorma is a heavyweight, native-extension, real-world app — and it shells out to heavyweight CLI tools, inkscape among them. Today that means "install inkscape on your host and hope the version fits." In the managed world it is a requires: edge: inkscape ships as its own isolated, signed payload with its own runtime constraint, mounted into metanorma's namespace at the consumer-declared path — and the host stays exactly as clean as it was before. pandoc, ghostscript, and every other "please also install…" CLI dependency generalize the same way.

Metanorma is the retirement gate for mnenv — the first real dogfood of the whole stack: payload build via tebako press (SDK native builds included), signed .tfs per (version × ruby line), the registry manifest, the dispatcher.

The same chain the chain-of-trust page unpicks link by link — compressed to the figure every other contract on this page leans on.

Look back over this page and try to find the ruby in it. The manifest's kind: language takes an engine name; the constraint algebra (range vs abi-line lock) is language-neutral; the dispatcher's cache-constraint-mount-exec loop never inspects the engine; the trust chain signs bytes, not rubies; the bootstrap's launcher ABI hands over images and an entry, not an interpreter. A python payload with engine: python, constraint: ">= 3.12, < 4.0" and a python runtime promising provides: { engine: python, abi_line: "3.12" } slot into the same contract and the same dispatch algebra — no new machinery, just new artifacts.

The one genuinely ruby-specific piece is the patch home — tamatebako/ruby, where upstream interpreter source gets its IO routed through TFS. Each new language needs exactly one of those (a tebako-runtime-python factory beside tebako-runtime-ruby) — everything downstream of it is already language-agnostic. Tebako was born an "advanced image packager for interpretive languages"; the contracts finally say so.

11 · Compared to what you use today.

One honest line each — what that tool gives you, and what tebako does instead.

Fairness note: several rows describe the managed mode, which is badged planned on this very page. The shipped standalone mode is the "one file" column; the rest is the locked design you're reading.

12 · Why it's amazing — the honest close.

Not adjectives — properties. Each is either shipped today or a direct consequence of a shipped mechanism.