tebako 0.15.1 → 0.15.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 349d5b0a59f98021f05bae37a7c62efd9282900f5d4c161e8567424a082d21a1
-  data.tar.gz: 74dabe977337bcbe8b63a82cc82653242e852542e629a8698f3f6828c59cebf3
+  metadata.gz: 8ec3da7722b76d52f17d341664974ff8ea5f5164feec924958cd2725238439d0
+  data.tar.gz: 2e244d8b29c27a4f884aa969961dca6968323d21376012bf539dbce28c5b7baa
 SHA512:
-  metadata.gz: eed8e60a9fe1c1185478c7f9c70d4a4e1af7c5f24c853c6a1ac85527c04bb7b281c5efdbc3cb9afd2ee31dd56e4d5a6d0e7975388ea180dc03d93fa4d703b845
-  data.tar.gz: 1355806d02bbe169d73d6ca746a5052d24dba4f49c398f514d25d8c35592b2d451f97629e60801d656ad755b70356d201a1211dd882a611fe1a083900b28c0e1
+  metadata.gz: ccf67b3e4bf6444ca31627b27e9876699f743cdac01e2ebea0cee29a9ea8113d24d5ef34d6b15ebd8461620c8e29bb3d75ef7332b5a1934e3b3d579130cdb871
+  data.tar.gz: 51695b16c05b1063678bc2f4c6042ae65c3111799f14f81a5d3982a30c4f94f74f7f28d2fa587c11cdcf509ff9a5f105428ed95eff693d47377337980d349177

data/CMakeLists.txt

@@ -175,7 +175,7 @@ string(CONCAT RUBY_API_VER ${RUBY_VER_BASE} ".0")
 # NOTE: the env override in def_ext_prj_g (tebako-tools) is currently broken
 # (`if (DEFINED ENV{${TAG})` is missing a closing brace, so the test never
 # fires); this default is the operative tag selection.
-def_ext_prj_g(DWARFS_WR "v0.12.8")
+def_ext_prj_g(DWARFS_WR "v0.12.9")
 
 # Provisions libtfs (prebuilt package or vcpkg toolchain for the source
 # build), the prebuilt mkdwarfs, and -- for the prebuilt path -- the
@@ -217,6 +217,7 @@ endif()
 def_ext_prj_g(PATCHELF "65e14792061c298f1d2bc44becd48a10cbf0bc81")
 
 set(LIBYAML_RUBY_OPTION "")
+set(RUBY_LIBS "")
 if(${RUBY_VER} VERSION_LESS "3.2.0")
   set(LIBYAML_RUBY_OPTION "--enable-bundled-libyaml")
 endif(${RUBY_VER} VERSION_LESS "3.2.0")
@@ -397,6 +398,16 @@ else(IS_DARWIN)
   if(RB_W32)
     string(CONCAT RUBY_C_FLAGS ${RUBY_C_FLAGS} " -DRB_W32=1")
     string(CONCAT RUBY_L_FLAGS ${RUBY_L_FLAGS} " -l:libstdc++.a -L${TLIBD}")
+    # vcpkg's static libcrypto.a (the CAPI engine, e_capi.obj) references
+    # the CryptoAPI certificate store (CertFreeCertificateContext & co.),
+    # but ruby's default mingw $LIBS lack -lcrypt32, so every ext/openssl
+    # have_func link probe failed with undefined Cert* references and the
+    # OpenSSL-1.1.0 accessor fallbacks in openssl_missing.c compiled
+    # against opaque 3.x structs (tebako#345). mkmf appends $LIBS after
+    # -lssl/-lcrypto, so LIBS here lands in the right order for static
+    # linking; advapi32/user32 cover the rest of the usual static-openssl
+    # system-lib tail.
+    set(RUBY_LIBS "-lcrypt32 -ladvapi32 -luser32")
     set(C_FLAGS_DEST cppflags)
   endif(RB_W32)
 
@@ -432,7 +443,8 @@ ExternalProject_Add(${RUBY_PRJ}
                                                         --with-out-ext=${RUBY_WITHOUT_EXT}    \
                                                         --prefix=${DATA_SRC_DIR}              \
                                                         ${C_FLAGS_DEST}=\"${RUBY_C_FLAGS}\"   \
-                                                        LDFLAGS=\"${RUBY_L_FLAGS}\""
+                                                        LDFLAGS=\"${RUBY_L_FLAGS}\"              \
+                                                        LIBS=\"${RUBY_LIBS}\""
   COMMAND   ruby ${EXE}/tebako-packager pass2 ${OSTYPE_TXT} ${RUBY_SOURCE_DIR} ${DEPS_LIB_DIR} ${DATA_SRC_DIR} ${RUBY_STASH_DIR} ${RUBY_VER}
   INSTALL_COMMAND  ""
 )

data/README.adoc

@@ -420,7 +420,7 @@ tebako press \
   [-c|--cwd=<package-current-working-directory>] \
   [-D|--devmode] \
   [-P|--patchelf] \
-  [-m|--mode=<bundle|both|application|runtime>] \
+  [-m|--mode=<lean|fat|classic|bundle|both|application|runtime>] \
   [-u|--ref=<runtime-reference>] \
   [-t|--tebafile=<path-to-tebafile>]
 ----
@@ -452,6 +452,7 @@ On Windows, the output file is automatically appended the `.exe` extension.
 
 *** in `runtime` mode, the runtime package is created at `tebako-runtime`.
 *** in `application` mode, the application package is created at `<current-folder>/<entry-point-base-name>`.
+*** in `lean`, `fat` and `classic` modes, the package is created at `<current-folder>/<entry-point-base-name>`.
 *** in `bundle` mode, the bundled package is created at `<current-folder>/<entry-point-base-name>`.
 *** in `both` mode, the runtime package is created at `<current-folder>/<entry-point-base-name>`,
 and the application package is created at `<current-folder>/<entry-point-base-name>.tebako`.
@@ -460,6 +461,7 @@ and the application package is created at `<current-folder>/<entry-point-base-na
 
 *** in `runtime` mode, the runtime package is named according to the `-o` option.
 *** in `application` mode, the application package is named according to the `-o` option.
+*** in `lean`, `fat` and `classic` modes, the package is named according to the `-o` option.
 *** in `bundle` mode, the bundled package is named according to the `-o` option.
 *** in `both` mode, the runtime package is named according to the `-o` option,
 and the application package is named according to the `-o` option with the `.tebako` extension.
@@ -502,10 +504,13 @@ For example, a package created at Ubuntu 20 system can be used on Ubuntu 22.
 NOTE: The feature is exeprimental, we may consider another approach in the future.
 
 `--mode=<mode>`::
-(optional, defaults to `bundle`)
-Package output mode, determines whether the runtime and/or application are
-to be separately packaged.
+(optional, defaults to `lean`)
+Package output mode, determines the package layout (three-part or runtime-stitched)
+and whether the runtime and/or application are separately packaged.
 
+`lean`::: Create a three-part package: the tebako-bootstrap launcher plus the application image slot(s) and a tpkg manifest trailer carrying the runtime reference. At first run the bootstrap resolves (downloads, verifies and caches) the referenced prebuilt runtime into the machine-wide cache (`~/.tebako` or `$TEBAKO_HOME`); subsequent runs of any lean package built for the same runtime share that cache entry. The output file is named according to the `-o` option.
+`fat`::: Like `lean`, but the runtime package is also embedded as a payload slot. The first run installs it into the cache without network access (works with `TEBAKO_OFFLINE=1`). The output file is named according to the `-o` option.
+`classic`::: Stitch the application image onto a prebuilt runtime package (the Stage-3A layout; identical to `bundle` with the default `--runtime prebuilt`). The output file is named according to the `-o` option.
 `bundle`::: Create a single package bundling both the runtime and application. The output file is named according to the `-o` option.
 `both`::: Create separate packages for the runtime and application. Outputs two separate files: one for the runtime at the location specified at the `-o {filename}` and one for the application at `{filename}.package`.
 `application`::: Create the application package only. The output file is named according to the `-o` option.

data/cmake/tebako-libtfs.cmake

@@ -82,9 +82,7 @@ endif()
 if(IS_GNU)
   set(LIBTFS_PLATFORM "linux-gnu-${__LIBTFS_ARCH}")
 elseif(IS_MUSL)
-  if(NOT __LIBTFS_ARCH STREQUAL "x86_64")
-    message(FATAL_ERROR "No prebuilt libtfs package for linux-musl-${__LIBTFS_ARCH}; use -DDWARFS_PRELOAD=OFF (source build)")
-  endif()
+  # musl-arm64 prebuilt packages first ship in libtfs v0.12.9
   set(LIBTFS_PLATFORM "linux-musl-${__LIBTFS_ARCH}")
 elseif(IS_DARWIN)
   set(LIBTFS_PLATFORM "macos-${__LIBTFS_ARCH}")

data/include/tebako/tpkg.h

@@ -48,7 +48,7 @@
  *     offset  size  field
  *        0     8    u64 offset (image start, absolute file offset)
  *        8     8    u64 size   (image length in bytes)
- *       16     4    u32 format_id (0=auto(magic), 1=dwarfs, 2=squashfs, 3=zip)
+ *       16     4    u32 format_id (0=auto(magic), 1=dwarfs, 2=squashfs, 3=zip, 4=runtime payload)
  *       20     4    u32 flags
  *       24   256    char mount_point[256] (UTF-8, NUL-padded)
  *
@@ -97,8 +97,8 @@ extern "C" {
 #define TPKG_MOUNT_POINT_LEN 256u
 #define TPKG_RUNTIME_REF_LEN 128u
 #define TPKG_MAGIC "TEBAKOTFS"
-#define TPKG_MAGIC_LEN 10u        /* including the terminating NUL */
-#define TPKG_MAGIC_PREFIX_LEN 4u  /* "TEBA": absent-vs-corrupt discriminator */
+#define TPKG_MAGIC_LEN 10u       /* including the terminating NUL */
+#define TPKG_MAGIC_PREFIX_LEN 4u /* "TEBA": absent-vs-corrupt discriminator */
 
 /* package_flags */
 #define TPKG_FLAG_LEAN 0x1u
@@ -108,6 +108,9 @@ extern "C" {
 #define TPKG_FORMAT_DWARFS 1u
 #define TPKG_FORMAT_SQUASHFS 2u
 #define TPKG_FORMAT_ZIP 3u
+/* A runtime payload slot (fat packages): the compressed language-runtime
+ * package the bootstrap installs into the shared cache on first run. */
+#define TPKG_FORMAT_RUNTIME 4u
 
 /* ---- error codes (returned by tpkg_errno) -------------------------------- */
 
@@ -157,7 +160,7 @@ int tpkg_read_mem(const void* data, size_t size, tpkg_manifest* out);
 int tpkg_write_fd(int fd, const tpkg_manifest* m);
 
 /* Magic-independent structural checks: version supported, slot_count in
- * 1..TPKG_MAX_SLOTS, offset+size non-overflowing, format_id <= TPKG_FORMAT_ZIP,
+ * 1..TPKG_MAX_SLOTS, offset+size non-overflowing, format_id <= TPKG_FORMAT_RUNTIME,
  * runtime_ref and mount_points NUL-terminated within their fixed fields. */
 int tpkg_validate(const tpkg_manifest* m);
 
@@ -220,19 +223,12 @@ enum {
 };
 
 /* slot record field offsets */
-enum {
-  TPKG__REC_OFFSET = 0,
-  TPKG__REC_SIZE = 8,
-  TPKG__REC_FORMAT = 16,
-  TPKG__REC_FLAGS = 20,
-  TPKG__REC_MOUNT = 24
-};
+enum { TPKG__REC_OFFSET = 0, TPKG__REC_SIZE = 8, TPKG__REC_FORMAT = 16, TPKG__REC_FLAGS = 20, TPKG__REC_MOUNT = 24 };
 
 /* wire sizes are fixed by the format; catch exotic padding at compile time */
 typedef char tpkg__assert_slot_size[(sizeof(tpkg_slot) == TPKG_SLOT_SIZE) ? 1 : -1];
-typedef char tpkg__assert_manifest_size[(sizeof(tpkg_manifest) ==
-                                         4 * sizeof(uint32_t) + TPKG_RUNTIME_REF_LEN +
-                                             TPKG_MAX_SLOTS * sizeof(tpkg_slot))
+typedef char tpkg__assert_manifest_size[(sizeof(tpkg_manifest) == 4 * sizeof(uint32_t) + TPKG_RUNTIME_REF_LEN +
+                                                                      TPKG_MAX_SLOTS * sizeof(tpkg_slot))
                                             ? 1
                                             : -1];
 
@@ -397,7 +393,7 @@ int tpkg_validate(const tpkg_manifest* m)
     if (s->size > UINT64_MAX - s->offset) {
       return tpkg__fail(TPKG_ERR_INVALID);
     }
-    if (s->format_id > TPKG_FORMAT_ZIP) {
+    if (s->format_id > TPKG_FORMAT_RUNTIME) {
       return tpkg__fail(TPKG_ERR_INVALID);
     }
     if (tpkg__strnlen(s->mount_point, TPKG_MOUNT_POINT_LEN) == TPKG_MOUNT_POINT_LEN) {

data/lib/tebako/bootstrap_manager.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+# Copyright (c) 2026 [Ribose Inc](https://www.ribose.com).
+# All rights reserved.
+# This file is a part of the Tebako project.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions
+# are met:
+# 1. Redistributions of source code must retain the above copyright
+#    notice, this list of conditions and the following disclaimer.
+# 2. Redistributions in binary form must reproduce the above copyright
+#    notice, this list of conditions and the following disclaimer in the
+#    documentation and/or other materials provided with the distribution.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+# ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+# TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+# PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS
+# BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+
+require_relative "runtime_manager"
+
+# Tebako - an executable packager
+module Tebako
+  # Resolution, download, verification and machine-wide caching of the
+  # tebako-bootstrap launcher binaries published by tamatebako/tebako-bootstrap.
+  # The launcher is the base binary of lean/fat three-part packages.
+  #
+  # Cache layout (rooted at $TEBAKO_HOME or ~/.tebako, shared with the
+  # runtime package cache):
+  #   bootstraps/tebako-bootstrap-<version>-<platform>/
+  #     tebako-bootstrap-<version>-<platform>[.exe]
+  #     sha256    -- digest the installed file was verified against
+  #     origin    -- URL the binary was downloaded from
+  #
+  # All download/verify/lock machinery is inherited from RuntimeManager; only
+  # the release-shape specifics (asset naming, manifest.json object format,
+  # SHA256SUMS index name, mirror env var) differ.
+  class BootstrapManager < RuntimeManager
+    DEFAULT_MIRROR = "https://github.com/tamatebako/tebako-bootstrap/releases/download"
+    BOOTSTRAPS_DIR = "bootstraps"
+    INDEX_FILES = ["manifest.json", "SHA256SUMS"].freeze
+
+    # tebako-bootstrap release consumed by default (TEBAKO_BOOTSTRAP_VERSION
+    # overrides). 0.2.0 is the first release that installs a fat package's
+    # runtime payload slot into the cache at first run.
+    BOOTSTRAP_VERSION = "0.2.0"
+    PAYLOAD_MIN_VERSION = "0.2.0"
+
+    class << self
+      def default_version
+        version = ENV.fetch("TEBAKO_BOOTSTRAP_VERSION", nil)
+        version.nil? || version.empty? ? BOOTSTRAP_VERSION : version.sub(/\Av/, "")
+      end
+
+      def resolve(platform, bootstrap_version: default_version)
+        new.resolve(platform, bootstrap_version: bootstrap_version)
+      end
+    end
+
+    def resolve(platform, bootstrap_version: self.class.default_version)
+      super(bootstrap_version, platform, tebako_version: bootstrap_version)
+    end
+
+    private
+
+    def default_mirror
+      DEFAULT_MIRROR
+    end
+
+    def mirror_env_var
+      "TEBAKO_BOOTSTRAP_MIRROR"
+    end
+
+    def index_files
+      INDEX_FILES
+    end
+
+    def cache_subdir
+      BOOTSTRAPS_DIR
+    end
+
+    def release_name
+      "tebako-bootstrap"
+    end
+
+    def entry_dir(_version, platform, bootstrap_version)
+      File.join(@cache_root, BOOTSTRAPS_DIR, "tebako-bootstrap-#{bootstrap_version}-#{platform}")
+    end
+
+    def runtime_filename(_version, platform, bootstrap_version)
+      suffix = platform.start_with?("windows") ? ".exe" : ""
+      "tebako-bootstrap-#{bootstrap_version}-#{platform}#{suffix}"
+    end
+
+    def runtime_ref(_version, platform, bootstrap_version)
+      "tebako-bootstrap@#{bootstrap_version} (#{platform})"
+    end
+
+    def find_entry(index, _version, platform, bootstrap_version)
+      entry = index.find { |candidate| candidate["platform"] == platform }
+      return entry if entry
+
+      platforms = index.map { |candidate| candidate["platform"] }
+      Tebako.packaging_error(131, "no tebako-bootstrap package for #{platform} (bootstrap #{bootstrap_version}). " \
+                                  "Available: #{platforms.join(", ")}.")
+    end
+
+    def offline_check(ref, bootstrap_version)
+      return unless offline?
+
+      Tebako.packaging_error(132, "#{ref} is not cached and downloads are disabled " \
+                                  "(release index: #{index_urls(bootstrap_version).join(", ")}; " \
+                                  "#{mirror_env_var}=#{@mirror})")
+    end
+
+    # tebako-bootstrap's manifest.json is an object
+    # ({name:, version:, assets: [{platform:, file:, sha256:}]}), not the
+    # entry array tebako-runtime-ruby publishes
+    def parse_manifest(body, _bootstrap_version)
+      manifest_assets(body)
+        .select { |asset| asset["platform"] && asset["file"] && asset["sha256"] }
+        .map { |asset| manifest_entry(asset) }
+    end
+
+    def manifest_assets(body)
+      data = JSON.parse(body)
+      assets = data.is_a?(Hash) ? data["assets"] : nil
+      raise IndexUnavailable, "manifest.json has no assets array" unless assets.is_a?(Array)
+
+      assets
+    rescue JSON::ParserError
+      raise IndexUnavailable, "manifest.json is not valid JSON"
+    end
+
+    def manifest_entry(asset)
+      { "platform" => asset["platform"], "filename" => asset["file"], "sha256" => asset["sha256"].downcase }
+    end
+
+    def parse_sha256sums(body, bootstrap_version)
+      pattern = /\Atebako-bootstrap-#{Regexp.escape(bootstrap_version)}-(.+?)(?:\.exe)?\z/
+      body.each_line.filter_map do |line|
+        sha256, file = line.strip.split(/\s+/, 2)
+        match = file && pattern.match(file.sub(/\A\*/, ""))
+        next unless match
+
+        { "platform" => match[1], "filename" => file.sub(/\A\*/, ""), "sha256" => sha256.downcase }
+      end
+    end
+  end
+end

data/lib/tebako/cli.rb

@@ -174,9 +174,10 @@ module Tebako
     DESC
 
     RUNTIME_DESCRIPTION = <<~DESC
-      Runtime provenance: 'prebuilt' resolves/downloads a prebuilt tebako runtime package and stitches the
-      #{" " * 65}# application image onto it (default for the 'bundle' mode); 'source' keeps the Stage-2 source build.
-      #{" " * 65}# Modes other than 'bundle' always build from source.
+      Runtime provenance: 'prebuilt' resolves/downloads a prebuilt tebako runtime package (default for the
+      #{" " * 65}# 'bundle', 'classic', 'lean' and 'fat' modes); 'source' keeps the Stage-2 source build
+      #{" " * 65}# (not available for 'lean'/'fat' -- the bootstrap resolves tebako-runtime-ruby releases
+      #{" " * 65}# at run time). Modes other than those always build from source.
     DESC
 
     IMAGE_DESCRIPTION = <<~DESC
@@ -184,6 +185,16 @@ module Tebako
       #{" " * 65}# must be distinct. Prebuilt runtime only.
     DESC
 
+    MODE_DESCRIPTION = <<~DESC
+      Tebako press mode, 'lean' by default.
+      #{" " * 65}# 'lean' presses a three-part package (tebako-bootstrap + application image(s) + tpkg trailer);
+      #{" " * 65}# the runtime is resolved into the shared cache at first run.
+      #{" " * 65}# 'fat' is 'lean' plus the runtime package as a payload slot -- the first run installs it
+      #{" " * 65}# into the cache without network access.
+      #{" " * 65}# 'classic' stitches the application image onto a prebuilt runtime (Stage-3A layout);
+      #{" " * 65}# 'bundle', 'both', 'application' and 'runtime' keep their legacy behaviors.
+    DESC
+
     desc "press", "Press tebako image"
     method_option :cwd, type: :string, aliases: "-c", required: false, desc: CWD_DESCRIPTION
     method_option :"log-level", type: :string, aliases: "-l", required: false, enum: %w[error warn debug trace],
@@ -197,8 +208,9 @@ module Tebako
                          enum: Tebako::RubyVersion::RUBY_VERSIONS.keys,
                          desc: "Tebako package Ruby version, #{Tebako::RubyVersion::DEFAULT_RUBY_VERSION} by default"
     method_option :patchelf, aliases: "-P", type: :boolean, desc: RGP_DESCRIPTION
-    method_option :mode, type: :string, aliases: "-m", required: false, enum: %w[bundle both runtime application],
-                         desc: "Tebako press mode, 'bundle' by default"
+    method_option :mode, type: :string, aliases: "-m", required: false,
+                         enum: %w[lean fat classic bundle both runtime application],
+                         desc: MODE_DESCRIPTION
     method_option :ref, type: :string, aliases: "-u", required: false, desc: REF_DESCRIPTION
     method_option :runtime, type: :string, required: false, enum: %w[prebuilt source], desc: RUNTIME_DESCRIPTION
     method_option :"build-runtime", type: :boolean, required: false,

data/lib/tebako/cli_helpers.rb

@@ -25,13 +25,16 @@
 # ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 # POSSIBILITY OF SUCH DAMAGE.
 
+require "digest"
 require "etc"
 require "fileutils"
 require "pathname"
 require "rbconfig"
 
+require_relative "bootstrap_manager"
 require_relative "codegen"
 require_relative "error"
+require_relative "launcher_abi"
 require_relative "options_manager"
 require_relative "runtime_manager"
 require_relative "scenario_manager"
@@ -86,8 +89,13 @@ module Tebako
       options_manager.process_gemfile(scenario_manager.gemfile_path) if scenario_manager.with_gemfile
       check_warnings(options_manager)
       puts options_manager.press_announce(scenario_manager.msys?)
+      dispatch_press(options_manager, scenario_manager)
+    end
 
-      if options_manager.prebuilt_runtime?
+    def dispatch_press(options_manager, scenario_manager)
+      if options_manager.three_part?
+        do_press_three_part(options_manager, scenario_manager)
+      elsif options_manager.prebuilt_runtime?
         do_press_prebuilt(options_manager, scenario_manager)
       else
         do_press_source(options_manager, scenario_manager)
@@ -104,7 +112,8 @@ module Tebako
     def do_press_prebuilt(options_manager, scenario_manager)
       Tebako::Packager.check_prebuilt_env!(options_manager.stash_dir, options_manager.deps_bin_dir)
       runtime_path = Tebako::RuntimeManager.resolve(options_manager.ruby_ver, options_manager.host_platform)
-      app_image = Tebako::Packager.build_app_image(options_manager, scenario_manager)
+      app_image = Tebako::Packager.build_app_image(options_manager, scenario_manager,
+                                                   Tebako::RuntimeManager.layout(runtime_path))
 
       images = [{ path: app_image, mount_point: scenario_manager.fs_mount_point,
                   format_id: Tebako::Stitcher::FORMAT_DWARFS }] + options_manager.images
@@ -113,6 +122,72 @@ module Tebako
       puts "Created tebako #{options_manager.output_type_first} at \"#{package}\""
     end
 
+    # Press a three-part package (Stage 3B): tebako-bootstrap + application
+    # image slot(s) + tpkg trailer with the runtime reference (launcher ABI
+    # v1). 'lean' (the default) resolves the runtime into the shared cache at
+    # first run; 'fat' additionally embeds the runtime package as a payload
+    # slot, so the first run installs it without any network access.
+    def do_press_three_part(options_manager, scenario_manager)
+      bootstrap_path, runtime_path = resolve_three_part_parts(options_manager)
+      app_image = Tebako::Packager.build_app_image(options_manager, scenario_manager,
+                                                   Tebako::RuntimeManager.layout(runtime_path))
+      payload_path = options_manager.fat? ? runtime_path : nil
+      images = three_part_images(options_manager, scenario_manager, app_image, payload_path)
+      package = "#{options_manager.package}#{scenario_manager.exe_suffix}"
+      stitch_three_part(options_manager, bootstrap_path, images, package, payload_path)
+      puts "Created tebako #{options_manager.output_type_first} at \"#{package}\""
+    end
+
+    def stitch_three_part(options_manager, bootstrap_path, images, package, payload_path)
+      Tebako::Stitcher.stitch(bootstrap_path, images: images, output: package, lean: true,
+                                              ruby_version: options_manager.ruby_ver,
+                                              launcher_abi: Tebako::LauncherAbi::VERSION,
+                                              runtime_sha256: payload_sha256(payload_path))
+    end
+
+    def payload_sha256(payload_path)
+      payload_path && Digest::SHA256.file(payload_path).hexdigest
+    end
+
+    # Validate the options and the packaging environment, then resolve the
+    # bootstrap and the runtime into the shared cache. The runtime is needed
+    # in both three-part modes: 'fat' embeds it as a payload slot, 'lean'
+    # uses its extracted layout to align the application image's arch
+    # conventions (and references it in the trailer for first-run resolution)
+    def resolve_three_part_parts(options_manager)
+      options_manager.runtime_source # validates the mode/provenance combination
+      check_bootstrap_version!(options_manager)
+      Tebako::Packager.check_prebuilt_env!(options_manager.stash_dir, options_manager.deps_bin_dir)
+      runtime_path = Tebako::RuntimeManager.resolve(options_manager.ruby_ver, options_manager.host_platform)
+      [Tebako::BootstrapManager.resolve(options_manager.host_platform), runtime_path]
+    end
+
+    def three_part_images(options_manager, scenario_manager, app_image, runtime_path)
+      images = [{ path: app_image, mount_point: scenario_manager.fs_mount_point,
+                  format_id: Tebako::Stitcher::FORMAT_DWARFS }] + options_manager.images
+      images << { path: runtime_path, mount_point: "", format_id: Tebako::Stitcher::FORMAT_RUNTIME } if runtime_path
+      images
+    end
+
+    # The fat payload slot is installed by the bootstrap at first run — a
+    # capability added in tebako-bootstrap 0.2.0
+    def check_bootstrap_version!(options_manager)
+      return unless options_manager.fat?
+
+      version = Tebako::BootstrapManager.default_version
+      minimum = Tebako::BootstrapManager::PAYLOAD_MIN_VERSION
+      return if payload_capable?(version, minimum)
+
+      Tebako.packaging_error(134, "fat mode requires tebako-bootstrap >= #{minimum} (selected: #{version}; " \
+                                  "set TEBAKO_BOOTSTRAP_VERSION to a payload-capable release)")
+    end
+
+    def payload_capable?(version, minimum)
+      Gem::Version.new(version) >= Gem::Version.new(minimum)
+    rescue ArgumentError
+      false
+    end
+
     def do_press_application(options_manager, scenario_manager)
       return unless %w[both application].include?(options_manager.mode)
 
@@ -121,7 +196,7 @@ module Tebako
     end
 
     def do_press_runtime(options_manager, scenario_manager)
-      return unless %w[both runtime bundle].include?(options_manager.mode)
+      return unless %w[both runtime bundle classic].include?(options_manager.mode)
 
       generate_files(options_manager, scenario_manager)
       merged_env = ENV.to_h.merge(scenario_manager.b_env)

data/lib/tebako/deploy_helper.rb

@@ -190,7 +190,11 @@ module Tebako
     def configure_commands_not_msys
       @cmd_suffix = ""
       @bat_suffix = ""
-      @force_ruby_platform = "false"
+      # Force the ruby (source) platform for gems: precompiled variants link
+      # against shared system libraries (libffi & co.) that do not exist
+      # inside a tebako package -- e.g. ffi-x86_64-linux-gnu fails to load in
+      # the memfs (tebako#343). msys has always forced this.
+      @force_ruby_platform = "true"
       @nokogiri_option = "--no-use-system-libraries"
     end
 

data/lib/tebako/error.rb

@@ -57,6 +57,9 @@ module Tebako
     127 => "Stitch input file is not accessible",
     128 => "Prebuilt runtime press requires the packaging environment (run 'tebako setup' first)",
     130 => "Option combination is not supported",
+    131 => "No tebako-bootstrap package for the requested platform",
+    132 => "TEBAKO_OFFLINE is set and the requested tebako-bootstrap package is not cached",
+    134 => "Fat mode requires a payload-capable tebako-bootstrap release",
     201 => "Warning. Could not create cache version file"
   }.freeze
 

data/lib/tebako/launcher_abi.rb

@@ -30,6 +30,12 @@ module Tebako
   # three-part package model (spec §4.4).
   #
   # A lean package is [tebako-bootstrap][.tfs image slots][tpkg trailer].
+  # A fat package has the same layout plus the runtime package itself as a
+  # payload slot (format_id TPKG_FORMAT_RUNTIME, empty mount point,
+  # ";sha256=<hex>" appended to the trailer's runtime_ref): at first run the
+  # bootstrap installs the payload into the shared cache instead of
+  # downloading it. Payload slots are never handed over as --tebako-image.
+  #
   # The bootstrap (tamatebako/tebako-bootstrap) parses the trailer of its own
   # executable, resolves the language runtime into the shared cache, and
   # execs it as:

data/lib/tebako/options_manager.rb

@@ -41,6 +41,13 @@ require_relative "version"
 module Tebako
   # Cli helpers
   class OptionsManager # rubocop:disable Metrics/ClassLength
+    # Press modes producing three-part packages (tebako-bootstrap + image
+    # slots + tpkg trailer): 'lean' resolves the runtime at first run, 'fat'
+    # additionally embeds it as a payload slot (self-installing, offline)
+    THREE_PART_MODES = %w[lean fat].freeze
+    # Modes whose default runtime provenance is a prebuilt runtime package
+    PREBUILT_DEFAULT_MODES = %w[bundle classic lean fat].freeze
+
     def initialize(options)
       @options = options
       @rv = Tebako::RubyVersion.new(@options["Ruby"])
@@ -157,14 +164,24 @@ module Tebako
     end
 
     def mode
-      @mode ||= @options["mode"].nil? ? "bundle" : @options["mode"]
+      @mode ||= @options["mode"].nil? ? "lean" : @options["mode"]
+    end
+
+    def three_part?
+      THREE_PART_MODES.include?(mode)
+    end
+
+    def fat?
+      mode == "fat"
     end
 
     # Runtime provenance: "prebuilt" (resolve/download a prebuilt runtime
-    # package and stitch the application image onto it) or "source" (the
-    # Stage-2 source build). Default is "prebuilt" for the bundle mode;
-    # other modes always build from source, and --build-runtime forces the
-    # source path everywhere (back-compat alias for '--runtime source').
+    # package) or "source" (the Stage-2 source build). Default is "prebuilt"
+    # for the bundle/classic/lean/fat modes; other modes always build from
+    # source, and --build-runtime forces the source path everywhere it is
+    # allowed (back-compat alias for '--runtime source'). The three-part
+    # modes (lean/fat) require prebuilt runtime packages: the bootstrap
+    # resolves tebako-runtime-ruby releases at run time.
     def runtime_source
       @runtime_source ||= checked_runtime_source(requested_runtime_source)
     end
@@ -246,7 +263,7 @@ module Tebako
         press_announce_application(is_msys)
       when "both"
         press_announce_both
-      when "bundle"
+      when "bundle", "classic", "lean", "fat"
         press_announce_bundle
       when "runtime"
         press_announce_runtime
@@ -290,7 +307,7 @@ module Tebako
     def press_announce_bundle
       <<~ANN
         Running tebako press at #{prefix}
-           Mode:                      'bundle'
+           Mode:                      '#{mode}'
            Ruby version:              '#{@ruby_ver}'
            Project root:              '#{root}'
            Application entry point:   '#{fs_entrance}'
@@ -374,14 +391,19 @@ module Tebako
     def requested_runtime_source
       explicit = @options["runtime"]
       return "source" if @options["build-runtime"]
-      return mode == "bundle" ? "prebuilt" : "source" if explicit.nil?
+      return PREBUILT_DEFAULT_MODES.include?(mode) ? "prebuilt" : "source" if explicit.nil?
 
       explicit
     end
 
     def checked_runtime_source(source)
-      if source == "prebuilt" && mode != "bundle"
-        Tebako.packaging_error(130, "--runtime prebuilt is supported in bundle mode only (mode: '#{mode}')")
+      if source == "prebuilt" && !PREBUILT_DEFAULT_MODES.include?(mode)
+        Tebako.packaging_error(130, "--runtime prebuilt is supported in bundle, classic, lean and fat modes only " \
+                                    "(mode: '#{mode}')")
+      end
+      if source == "source" && three_part?
+        Tebako.packaging_error(130, "mode '#{mode}' requires a prebuilt runtime package " \
+                                    "(the bootstrap resolves tebako-runtime-ruby releases at first run)")
       end
       source
     end
@@ -399,7 +421,7 @@ module Tebako
 
     def host_arch_id(arch)
       case arch
-      when /^(x86_64|amd64)$/ then "x86_64"
+      when /^(x86_64|amd64|x64)$/ then "x86_64"
       when /^(aarch64|arm64)$/ then "arm64"
       else
         Tebako.packaging_error(112, arch)

data/lib/tebako/packager/pass1_patch.rb

@@ -203,6 +203,21 @@ module Tebako
           "/* tebako patched */ static const struct vktable *console_win32_vk(const char *, size_t);"
       }.freeze
 
+      # Ruby's win32.c defines clock_gettime/clock_getres fallbacks with no
+      # HAVE_* configure guard (at least through 3.4); modern mingw-w64
+      # winpthreads headers (pthread_time.h, pulled in by time.h) carry
+      # static-inline definitions of the same symbols, so the toolchain
+      # build fails with redefinition errors. Rename ruby's fallbacks
+      # before the toolchain build; the CRT/winpthreads implementations
+      # (which configure detects) serve the calls. Pass2 re-applies the
+      # same rename from pristine sources for the final build.
+      WIN32_WIN32_C_CLOCK_PATCH = {
+        "clock_gettime(clockid_t clock_id, struct timespec *sp)" =>
+          "_dummy_clock_gettime(clockid_t clock_id, struct timespec *sp)",
+        "clock_getres(clockid_t clock_id, struct timespec *sp)" =>
+          "_dummy_clock_getres(clockid_t clock_id, struct timespec *sp)"
+      }.freeze
+
       def patch_map
         pm = msys_patches
         pm.merge!(super)
@@ -246,7 +261,11 @@ module Tebako
           "ext/openssl/extconf.rb" => OPENSSL_EXTCONF_RB_PATCH,
           # ....................................................
           # Fix the signature of console_win32_vk
-          "ext/io/console/win32_vk.inc" => EXT_IO_CONSOLE_WIN32_VK_INC_PATCH
+          "ext/io/console/win32_vk.inc" => EXT_IO_CONSOLE_WIN32_VK_INC_PATCH,
+          # ....................................................
+          # Rename ruby's clock_gettime/clock_getres fallbacks before the
+          # toolchain build (winpthreads static-inline collision)
+          "win32/win32.c" => WIN32_WIN32_C_CLOCK_PATCH
         }
       end
 

data/lib/tebako/packager/pass2msys_patch.rb

@@ -114,6 +114,9 @@ module Tebako
       "#if defined _MSC_VER && _MSC_VER <= 1200" =>
         "#{PatchLiterals::C_FILE_SUBST_LESS}\n#if defined _MSC_VER && _MSC_VER <= 1200",
       "len = GetCurrentDirectoryW(0, NULL);" => WIN32_WIN32_C_MSYS_SUBST,
+      # Keep the clock renames in sync with Pass1MSysPatch::WIN32_WIN32_C_CLOCK_PATCH:
+      # pass1 applies them for the toolchain build, this pass re-applies them
+      # from pristine sources for the final build
       "clock_gettime(clockid_t clock_id, struct timespec *sp)" =>
         "_dummy_clock_gettime(clockid_t clock_id, struct timespec *sp)",
       "clock_getres(clockid_t clock_id, struct timespec *sp)" =>

data/lib/tebako/packager/patch_helpers.rb

@@ -76,7 +76,9 @@ module Tebako
 
         def recreate(dirname)
           FileUtils.rm_rf(dirname, noop: nil, verbose: nil, secure: true)
-          FileUtils.mkdir(dirname)
+          # mkdir_p: in three-part/prebuilt press flows no cmake configure runs,
+          # so the parent output folder may not exist yet
+          FileUtils.mkdir_p(dirname)
         end
 
         def restore_and_save(fname, strict: true)

data/lib/tebako/packager.rb

@@ -129,16 +129,72 @@ module Tebako
       # Deploy the application and build its DwarFS image for stitching onto
       # a prebuilt runtime. Same layout as the bundle-mode image, plus an
       # entry dispatcher at /local/stub.rb (the runtime's compiled-in entry).
-      def build_app_image(options_manager, scenario_manager) # rubocop:disable Metrics/AbcSize
+      # When layout_dir is given (the resolved runtime's extracted layout),
+      # the image's arch conventions are aligned to the runtime's: ruby's
+      # compiled-in search paths come from the runtime build, while the
+      # local packaging environment names arch directories after the press
+      # machine -- on macOS the arch string embeds the kernel version
+      # (arm64-darwin23 vs arm64-darwin24), so they differ whenever press
+      # and runtime were built on different macOS releases.
+      def build_app_image(options_manager, scenario_manager, layout_dir = nil) # rubocop:disable Metrics/AbcSize
         init(options_manager.stash_dir, options_manager.data_src_dir, options_manager.data_pre_dir,
              options_manager.data_bin_dir)
         deploy(options_manager.data_src_dir, options_manager.data_pre_dir, options_manager.rv,
                options_manager.root, scenario_manager.fs_entrance, options_manager.cwd)
+        align_layout_to_runtime!(options_manager.data_src_dir, layout_dir, options_manager.rv) if layout_dir
         write_entry_dispatcher(options_manager.data_src_dir, scenario_manager, options_manager.cwd)
         mkdwarfs(options_manager.deps_bin_dir, options_manager.data_bundle_file, options_manager.data_src_dir)
         options_manager.data_bundle_file
       end
 
+      # Rename the image's arch directories to the runtime's names and drop
+      # in the runtime's own rbconfig.rb. No-op when the conventions already
+      # match (always the case off macOS, where the arch string carries no
+      # OS version).
+      def align_layout_to_runtime!(data_src_dir, layout_dir, ruby_ver)
+        align_stdlib_arch!(data_src_dir, layout_dir, ruby_ver.api_version)
+        align_gem_ext_arch!(data_src_dir, layout_dir, ruby_ver.api_version)
+      end
+
+      def align_stdlib_arch!(data_src_dir, layout_dir, api_ver)
+        runtime_arch = arch_dir_of(File.join(layout_dir, "lib", "ruby", api_ver), "rbconfig.rb")
+        image_arch = arch_dir_of(File.join(data_src_dir, "lib", "ruby", api_ver), "rbconfig.rb")
+        return if runtime_arch.nil? || image_arch.nil? || runtime_arch == image_arch
+
+        puts "   ... aligning app image layout to the runtime (#{image_arch} -> #{runtime_arch})"
+        FileUtils.mv(File.join(data_src_dir, "lib", "ruby", api_ver, image_arch),
+                     File.join(data_src_dir, "lib", "ruby", api_ver, runtime_arch))
+        FileUtils.cp(File.join(layout_dir, "lib", "ruby", api_ver, runtime_arch, "rbconfig.rb"),
+                     File.join(data_src_dir, "lib", "ruby", api_ver, runtime_arch, "rbconfig.rb"))
+      end
+
+      # Native-gem extensions dir uses the dashed flavor of the arch string
+      # (arm64-darwin-23); align it to the runtime's as well
+      def align_gem_ext_arch!(data_src_dir, layout_dir, api_ver)
+        img_ext = File.join(data_src_dir, "lib", "ruby", "gems", api_ver, "extensions")
+        rt_ext = File.join(layout_dir, "lib", "ruby", "gems", api_ver, "extensions")
+        runtime_ext = first_dir(rt_ext)
+        return if runtime_ext.nil? || !Dir.exist?(img_ext)
+
+        Dir.children(img_ext).each do |d|
+          next if d == runtime_ext || !File.directory?(File.join(img_ext, d))
+
+          FileUtils.mv(File.join(img_ext, d), File.join(img_ext, runtime_ext))
+        end
+      end
+
+      def arch_dir_of(dir, marker)
+        return nil unless Dir.exist?(dir)
+
+        Dir.children(dir).find { |d| File.exist?(File.join(dir, d, marker)) }
+      end
+
+      def first_dir(dir)
+        return nil unless Dir.exist?(dir)
+
+        Dir.children(dir).find { |d| File.directory?(File.join(dir, d)) }
+      end
+
       # The prebuilt runtime packages are pressed in 'runtime' mode, so their
       # compiled-in entry point is /local/stub.rb. A stitched package mounts
       # the application image as the root filesystem; the dispatcher written

data/lib/tebako/ruby_version.rb

@@ -46,7 +46,14 @@ module Tebako
       "3.3.6" => "8dc48fffaf270f86f1019053f28e51e4da4cce32a36760a0603a9aee67d7fd8d",
       "3.3.7" => "9c37c3b12288c7aec20ca121ce76845be5bb5d77662a24919651aaf1d12c8628",
       "3.4.1" => "3d385e5d22d368b064c817a13ed8e3cc3f71a7705d7ed1bae78013c33aa7c87f",
-      "3.4.2" => "41328ac21f2bfdd7de6b3565ef4f0dd7543354d37e96f157a1552a6bd0eb364b"
+      "3.4.2" => "41328ac21f2bfdd7de6b3565ef4f0dd7543354d37e96f157a1552a6bd0eb364b",
+      "4.0.0" => "2e8389c8c072cb658c93a1372732d9eac84082c88b065750db1e52a5ac630271",
+      "4.0.1" => "3924be2d05db30f4e35f859bf028be85f4b7dd01714142fd823e4af5de2faf9d",
+      "4.0.2" => "51502b26b50b68df4963336ca41e368cde92c928faf91654de4c4c1791f82aac",
+      "4.0.3" => "77964acc370d5c8375b9502e5ba6c13c03ef91ab9eb9f521c84fb42b9c9a6b0f",
+      "4.0.4" => "f35f6edfa3dabb3f723f9d0cf1906c6512ae77f4e412ab1e68cc6e91d230fa80",
+      "4.0.5" => "7d6149079a63f8ae1d326c9fa65c6019ba2dc3155eae7b39159817911c88958e",
+      "4.0.6" => "837d299e8f7ddf2be31a229a7a7e019d354979825117989acb3b32b1a9be262a"
     }.freeze
 
     MIN_RUBY_VERSION_WINDOWS = "3.1.6"
@@ -72,38 +79,40 @@ module Tebako
       @lib_version ||= "#{@ruby_version.split(".")[0..1].join}0"
     end
 
+    # Version gates compare numerically so 4.x lines fall out naturally
+    # (string indexing broke the moment the major version hit 4)
     def ruby3x?
-      @ruby3x ||= @ruby_version[0] == "3"
+      @ruby3x ||= version_at_least?(3, 0)
     end
 
     def ruby31?
-      @ruby31 ||= ruby3x? && @ruby_version[2].to_i >= 1
+      @ruby31 ||= version_at_least?(3, 1)
     end
 
     def ruby32?
-      @ruby32 ||= ruby3x? && @ruby_version[2].to_i >= 2
+      @ruby32 ||= version_at_least?(3, 2)
     end
 
     def ruby32only?
-      @ruby32only ||= ruby3x? && @ruby_version[2] == "2"
+      @ruby32only ||= major_minor == [3, 2]
     end
 
     def ruby33?
-      @ruby33 ||= ruby3x? && @ruby_version[2].to_i >= 3
+      @ruby33 ||= version_at_least?(3, 3)
     end
 
     def ruby33only?
-      @ruby33only ||= ruby3x? && @ruby_version[2] == "3"
+      @ruby33only ||= major_minor == [3, 3]
     end
 
     def ruby3x7?
       @ruby3x7 ||= ruby34? ||
-                   (ruby33only? && @ruby_version[4].to_i >= 7) ||
-                   (ruby32only? && @ruby_version[4].to_i >= 7)
+                   (ruby33only? && patch_version >= 7) ||
+                   (ruby32only? && patch_version >= 7)
     end
 
     def ruby34?
-      @ruby34 ||= ruby3x? && @ruby_version[2].to_i >= 4
+      @ruby34 ||= version_at_least?(3, 4)
     end
 
     def run_checks
@@ -112,6 +121,22 @@ module Tebako
       version_check_msys
     end
 
+    private
+
+    def major_minor
+      @major_minor ||= @ruby_version.split(".").first(2).map(&:to_i)
+    end
+
+    def patch_version
+      @patch_version ||= @ruby_version.split(".")[2].to_i
+    end
+
+    def version_at_least?(major, minor)
+      (major_minor <=> [major, minor]) >= 0
+    end
+
+    public
+
     def version_check
       return if RUBY_VERSIONS.key?(@ruby_version)
 

data/lib/tebako/runtime_manager.rb

@@ -31,6 +31,7 @@ require "json"
 require "net/http"
 require "uri"
 
+require_relative "build_helpers"
 require_relative "error"
 require_relative "version"
 
@@ -83,11 +84,15 @@ module Tebako
       def resolve(ruby_version, platform, tebako_version: Tebako::VERSION)
         new.resolve(ruby_version, platform, tebako_version: tebako_version)
       end
+
+      def layout(runtime_path)
+        new.layout(runtime_path)
+      end
     end
 
     def initialize(cache_root: nil, mirror: nil, lock_timeout: LOCK_TIMEOUT, retry_delay: RETRY_DELAY)
       @cache_root = cache_root || self.class.default_cache_root
-      @mirror = (mirror || ENV.fetch("TEBAKO_RUNTIME_MIRROR", nil) || DEFAULT_MIRROR).sub(%r{/+\z}, "")
+      @mirror = (mirror || ENV.fetch(mirror_env_var, nil) || default_mirror).sub(%r{/+\z}, "")
       @lock_timeout = lock_timeout
       @retry_delay = retry_delay
     end
@@ -105,8 +110,24 @@ module Tebako
       executable
     end
 
+    # Extract the runtime package's filesystem layout next to the cached
+    # package (idempotent) and return the layout root. The layout is the
+    # authoritative source of the runtime's arch conventions (rbconfig
+    # location, gem extension dir naming), which the application image must
+    # match: ruby's compiled-in search paths come from the runtime build,
+    # while a local packaging environment names them after the press machine
+    # (macOS embeds the kernel version, e.g. arm64-darwin23 vs -darwin24).
+    def layout(runtime_path)
+      layout_dir = File.join(File.dirname(runtime_path), "layout")
+      return layout_dir if File.directory?(File.join(layout_dir, "lib"))
+
+      FileUtils.mkdir_p(layout_dir)
+      Tebako::BuildHelpers.run_with_capture_v([runtime_path, "--tebako-extract", layout_dir])
+      layout_dir
+    end
+
     def entries
-      base = File.join(@cache_root, RUNTIMES_DIR)
+      base = File.join(@cache_root, cache_subdir)
       return [] unless Dir.exist?(base)
 
       Dir.children(base).sort.filter_map do |name|
@@ -131,6 +152,29 @@ module Tebako
 
     private
 
+    # ---- extension points for BootstrapManager (tebako-bootstrap release
+    # resolution); overridden there, everything else is shared machinery ----
+
+    def default_mirror
+      DEFAULT_MIRROR
+    end
+
+    def mirror_env_var
+      "TEBAKO_RUNTIME_MIRROR"
+    end
+
+    def index_files
+      INDEX_FILES
+    end
+
+    def cache_subdir
+      RUNTIMES_DIR
+    end
+
+    def release_name
+      "tebako-runtime-ruby"
+    end
+
     def install(executable, ruby_version, platform, tebako_version)
       ref = runtime_ref(ruby_version, platform, tebako_version)
       offline_check(ref, tebako_version)
@@ -146,7 +190,7 @@ module Tebako
 
       Tebako.packaging_error(123, "#{ref} is not cached and downloads are disabled " \
                                   "(release index: #{index_urls(tebako_version).join(", ")}; " \
-                                  "TEBAKO_RUNTIME_MIRROR=#{@mirror})")
+                                  "#{mirror_env_var}=#{@mirror})")
     end
 
     def find_entry(index, ruby_version, platform, tebako_version)
@@ -178,14 +222,14 @@ module Tebako
 
     def fetch_index(tebako_version)
       tried = []
-      INDEX_FILES.each do |name|
+      index_files.each do |name|
         return parse_index(name, fetch_text(index_url(name, tebako_version)), tebako_version)
       rescue IndexUnavailable
         tried << index_url(name, tebako_version)
       rescue DownloadFailed => e
         Tebako.packaging_error(122, e.message)
       end
-      Tebako.packaging_error(124, "tebako-runtime-ruby release v#{tebako_version} provides no usable package " \
+      Tebako.packaging_error(124, "#{release_name} release v#{tebako_version} provides no usable package " \
                                   "index (tried: #{tried.join(", ")})")
     end
 
@@ -333,7 +377,7 @@ module Tebako
     end
 
     def index_urls(tebako_version)
-      INDEX_FILES.map { |name| index_url(name, tebako_version) }
+      index_files.map { |name| index_url(name, tebako_version) }
     end
 
     def package_url(filename, tebako_version)

data/lib/tebako/stitcher.rb

@@ -75,7 +75,10 @@ module Tebako
     FORMAT_DWARFS = 1
     FORMAT_SQUASHFS = 2
     FORMAT_ZIP = 3
-    FORMAT_IDS = (FORMAT_AUTO..FORMAT_ZIP).freeze
+    # Runtime payload slot of a fat package: installed into the shared cache
+    # by the bootstrap at first run, never mounted (tpkg.h TPKG_FORMAT_RUNTIME)
+    FORMAT_RUNTIME = 4
+    FORMAT_IDS = (FORMAT_AUTO..FORMAT_RUNTIME).freeze
 
     # Header field offsets
     OFF_PACKAGE_FLAGS = 14
@@ -89,17 +92,21 @@ module Tebako
       # copy of the runtime at +runtime_path+, writing +output+.
       # lean: true marks the package LEAN and records runtime_ref
       # ("ruby@<ruby_version>;tebako=<tebako_version>"); classic packages
-      # carry an empty runtime_ref.
+      # carry an empty runtime_ref. runtime_sha256 appends ";sha256=<hex>" to
+      # the runtime_ref — the checksum the bootstrap verifies a fat package's
+      # runtime payload slot against before installing it into the cache.
       def stitch(runtime_path, images:, output:, lean: false, ruby_version: nil, # rubocop:disable Metrics/ParameterLists
-                 tebako_version: Tebako::VERSION, launcher_abi: 0)
+                 tebako_version: Tebako::VERSION, launcher_abi: 0, runtime_sha256: nil)
         images = normalize_images(images)
         validate_inputs!(runtime_path, images, lean, ruby_version)
+        validate_runtime_sha256!(runtime_sha256)
 
         FileUtils.mkdir_p(File.dirname(output))
         FileUtils.cp(runtime_path, output)
         FileUtils.chmod(0o755, output)
 
-        append(images, output, package_flags(lean), runtime_ref(lean, ruby_version, tebako_version), launcher_abi)
+        append(images, output, package_flags(lean), runtime_ref(lean, ruby_version, tebako_version, runtime_sha256),
+               launcher_abi)
         resign_if_needed(output)
         output
       end
@@ -157,6 +164,8 @@ module Tebako
         seen = {}
         images.each do |image|
           validate_image!(image)
+          next if image[:format_id] == FORMAT_RUNTIME # payload slots are never mounted
+
           mount = image[:mount_point]
           Tebako.packaging_error(126, "duplicate mount point '#{mount}'") if seen[mount]
 
@@ -166,7 +175,7 @@ module Tebako
 
       def validate_image!(image)
         unless FORMAT_IDS.cover?(image[:format_id])
-          Tebako.packaging_error(126, "invalid format_id #{image[:format_id]} (0..3 expected)")
+          Tebako.packaging_error(126, "invalid format_id #{image[:format_id]} (0..4 expected)")
         end
         return unless image[:mount_point].bytesize >= MOUNT_POINT_LEN
 
@@ -174,14 +183,21 @@ module Tebako
                                "mount point '#{image[:mount_point][0, 32]}...' exceeds #{MOUNT_POINT_LEN - 1} bytes")
       end
 
+      def validate_runtime_sha256!(runtime_sha256)
+        return if runtime_sha256.nil? || runtime_sha256.match?(/\A[0-9a-f]{64}\z/)
+
+        Tebako.packaging_error(126, "runtime_sha256 must be 64 lowercase hex characters")
+      end
+
       def package_flags(lean)
         lean ? FLAG_LEAN : 0
       end
 
-      def runtime_ref(lean, ruby_version, tebako_version)
+      def runtime_ref(lean, ruby_version, tebako_version, runtime_sha256)
         return "" unless lean
 
         ref = "ruby@#{ruby_version};tebako=#{tebako_version}"
+        ref += ";sha256=#{runtime_sha256}" if runtime_sha256
         if ref.bytesize >= RUNTIME_REF_LEN
           Tebako.packaging_error(126, "runtime_ref '#{ref}' exceeds #{RUNTIME_REF_LEN - 1} bytes")
         end

data/lib/tebako/version.rb

@@ -26,5 +26,5 @@
 # POSSIBILITY OF SUCH DAMAGE.
 
 module Tebako
-  VERSION = "0.15.1"
+  VERSION = "0.15.3"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tebako
 version: !ruby/object:Gem::Version
-  version: 0.15.1
+  version: 0.15.3
 platform: ruby
 authors:
 - Ribose Inc.
@@ -212,6 +212,7 @@ files:
 - include/tebako/tebako-prism.h
 - include/tebako/tpkg.h
 - lib/tebako.rb
+- lib/tebako/bootstrap_manager.rb
 - lib/tebako/build_helpers.rb
 - lib/tebako/cache_manager.rb
 - lib/tebako/cli.rb