tebako-release 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: cd3ef0747dda2fc3ea4d7fcd7f35fe9aeba66cec808604ff7933ba3f644e0191
+  data.tar.gz: 24374660ac6c58c5b0d226b67224d84b1f18f3f0f415c666657a6b9aeeebe015
+SHA512:
+  metadata.gz: 15a427891a21fb83094aa5f6dd1970a5efe45cb9431b8ab62ad2e7b6faea108c26d7ca66b2743c332c8f4600b3072fa131f0b5002496c90448a5f60da7671305
+  data.tar.gz: 23ecefb7508b57e6d9c907e867b8825b54b0915a084a04ff7cf88d1c81f42a1c469b01cd4a6fc1ade5faddfa2a250860e94306c69738c37e8d58d4c33fdd0981

data/LICENSE.md

@@ -0,0 +1,24 @@
+Copyright (c) 2026 [Ribose Inc](https://www.ribose.com).
+All rights reserved.
+This file is a part of tamatebako
+
+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.

data/README.md

@@ -0,0 +1,66 @@
+# tebako-release-tooling
+
+The tebako factories' release machinery — the **single owner** of the per-leg
+publish uploader and the no-fold OpenPGP release signer that every runtime
+factory (ruby, python, openjdk, …) consumes. Ecosystem invariant 10: the
+machinery exists exactly once; factories declare their identity and policy
+through a small adapter file and pin this gem — they never carry copies.
+
+## What ships here
+
+- **`TebakoRelease::Uploader`** (`tebako-release upload`) — the spec 13 §2a
+  de-rendezvoused publish: each build leg uploads only the write-once names
+  it owns (payloads byte-immutable per name, per-asset `.sha256` sidecars,
+  per-package `.manifest.json` shards), with the convergence, rate-limit
+  ride-out, and settled-ledger machinery earned against the named incidents
+  of the v0.16.x line.
+- **`TebakoRelease::Signer`** (`tebako-release sign`) — spec 09 §5's no-fold
+  signing: every served name gets its own detached `.asc`, provenance-checked
+  against the release listing's digest, with the young-release-object
+  served-bytes convergence.
+- **`TebakoRelease::Bundler`** — spec 36's deterministic bundle builder:
+  one `<stem>.tar.gz` per leg (exe + env image + support DLLs + a closing
+  in-bundle SHA256SUMS; fixed member order, mtime=0 — identical inputs
+  yield identical bytes). A factory opts into the bundle-era publish shape
+  through its adapter (`bundle_publish? → true`); the per-file shape stays
+  the default for pre-bundle lines.
+- **`TebakoRelease::Platform`** — the release-side platform vocabulary
+  (the `(os, arch) → host_id` table; mirrors `tpkg::Platform`, drift fails
+  loudly in factory CI).
+
+## Consuming factory contract
+
+A factory adds the gem, pinned through its `contract.yml` SSOT:
+
+```ruby
+# Gemfile
+gem "tebako-release",
+    git: "https://github.com/tamatebako/tebako-release-tooling.git",
+    tag: YAML.load_file("contract.yml").fetch("release_tooling")
+```
+
+and declares itself once in `scripts/release_adapter.rb`:
+
+```ruby
+TebakoRelease.configure(
+  repo: "tamatebako/tebako-runtime-ruby",   # whose releases this run manages
+  language: "ruby",                          # EXPECTED_RUBY_MATRIX, ruby_version key
+  title_prefix: "Tebako runtime packages",
+  contract_yml: File.expand_path("../contract.yml", __dir__),
+  adapter: RubyReleaseAdapter.new            # capable_pair? / capabilities / dll_install_name
+)
+```
+
+CI then calls `bundle exec tebako-release upload` (publish legs) and
+`bundle exec tebako-release sign` (sign legs). Sign-only consumers can skip
+the adapter and set `TEBAKO_RELEASE_REPO` instead.
+
+## force_rebuild, the release-object rule
+
+Payload assets are byte-immutable per name — the uploader **never** deletes a
+published payload asset to replace it (delete → re-upload of the same name is
+the 422 wedge; tebako-runtime-ruby#189). A forced republication recreates the
+**release object** once, coordinator-side, before any leg fans out
+(`gh release delete <tag> --cleanup-tag false` … the first leg's
+race-safe create re-makes it), turning every leg's publish into pure creates.
+Operator-run re-uploads follow the same rule by hand.

data/exe/tebako-release

@@ -0,0 +1,37 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Copyright (c) 2026 [Ribose Inc](https://www.ribose.com).
+# All rights reserved.
+# This file is a part of tamatebako
+
+# CI log truth: stdout to a pipe is block-buffered, and the runner stamps
+# each line at FLUSH time — in the 2026-08-20 wedge incident's log, lines
+# written minutes apart (sleeps included) appeared 2 ms apart. Flush every
+# line so the log's timestamps are the writes' real times.
+$stdout.sync = true
+
+require "tebako_release"
+
+command = ARGV.shift
+
+# The consuming factory's adapter file declares TebakoRelease.configure(...)
+# — repo, language, version grammar, and the policy callbacks. Sign-only
+# invocations may run adapter-less on TEBAKO_RELEASE_REPO alone.
+adapter = ENV.fetch("TEBAKO_RELEASE_ADAPTER", "scripts/release_adapter.rb")
+require File.expand_path(adapter) if File.file?(adapter)
+
+case command
+when "upload"
+  TebakoRelease::Uploader.new.run
+when "sign"
+  begin
+    TebakoRelease::Signer.new.sign_release
+  rescue TebakoRelease::Signer::SigningGateError, TebakoRelease::Error, KeyError => e
+    warn e.message
+    exit 1
+  end
+else
+  warn "usage: tebako-release <upload|sign>"
+  exit 64
+end

data/lib/tebako_release/adapter.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+# Copyright (c) 2026 [Ribose Inc](https://www.ribose.com).
+# All rights reserved.
+# This file is a part of tamatebako
+
+module TebakoRelease
+  # The factory-policy surface — the one seam through which a consuming
+  # factory's own vocabulary reaches the release machinery. Factories
+  # subclass this (or pass any object responding to the same methods) in
+  # their adapter file; the defaults describe a runtime with no
+  # capability gates, no capabilities display metadata, no DLL facet,
+  # plain string version matrix rows, and a semver version grammar.
+  class Adapter
+    # (os id, arch id, runtime version) → false when the factory never
+    # builds that combination (the audit must never expect it). Default:
+    # every pair is capable.
+    def capable_pair?(_os, _arch, _version)
+      true
+    end
+
+    # The additive capabilities line of a manifest entry: display metadata
+    # owned by the factory that compiled the runtime — never a selector
+    # axis. Default: none.
+    def capabilities(version:, platform_id:)
+      _ = version
+      _ = platform_id
+      []
+    end
+
+    # The PE name the store materializes next to a windows exe so its
+    # imports resolve (nil → the runtime ships no DLL facet).
+    def dll_install_name(_version, _host_id)
+      nil
+    end
+
+    # The prepare job's version matrix rows → version strings. Default:
+    # rows ARE the version strings; factories whose rows carry extra keys
+    # (a src_sha256 cache key) override.
+    def expected_versions(rows)
+      rows.map { |row| row.is_a?(Hash) ? row.fetch("version") : row }
+    end
+
+    # The version capture of the package-name grammar, as a regex SOURCE
+    # (the consuming factory's version-line model owns it).
+    def version_grammar_source
+      "\\d+\\.\\d+\\.\\d+"
+    end
+
+    # Spec 36's publish shape: when true, each leg publishes ONE bundle
+    # (<stem>.tar.gz — exe + env image + DLLs + in-bundle SHA256SUMS) plus
+    # its sidecar and shard, instead of the per-file asset enumeration.
+    # Default off: a factory opts in deliberately, with the bundle-era
+    # resolver shipped downstream (spec 36 §4's compat window).
+    def bundle_publish?
+      false
+    end
+  end
+end

data/lib/tebako_release/bundler.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+# Copyright (c) 2026 [Ribose Inc](https://www.ribose.com).
+# All rights reserved.
+# This file is a part of tamatebako
+
+require "digest"
+require "rubygems/package"
+require "zlib"
+
+module TebakoRelease
+  # Spec 36 §2 — the deterministic tar.gz runtime bundle: ONE distribution
+  # artifact per (version × triplet) leg carrying the interpreter exe, the
+  # env image, and any windows support DLLs, closed by an in-bundle
+  # SHA256SUMS. The bundle is the publish unit on bundle-era lines: the
+  # per-file asset enumeration (exe + image + per-asset sidecars, each
+  # signed) costs ~10–14 release assets per leg; the bundle costs 3–5.
+  #
+  # Determinism is a publish-economy property, not a promise to consumers:
+  # identical inputs must yield identical bytes so a re-run's digest-match
+  # skip stays cheap (fixed member order, mtime=0 everywhere, no gzip
+  # original-name field).
+  class Bundler
+    BUNDLE_SUFFIX = ".tar.gz"
+    SUMS_NAME = "SHA256SUMS"
+
+    # Member modes as the store materializes them (spec 05 §3): the exe is
+    # 0755, the env image 0444, support DLLs plain read-only data.
+    EXE_MODE = 0o755
+    IMAGE_MODE = 0o444
+    DLL_MODE = 0o444
+
+    def self.bundle_name_for(stem)
+      "#{stem}#{BUNDLE_SUFFIX}"
+    end
+
+    # Build <dir>/<stem>.tar.gz from the leg's staged members.
+    # members: exe Pathname (required), image Pathname (required — a
+    # bundle without its env image is not a runtime), dlls (zero or
+    # more). Returns the bundle Pathname.
+    def build(dir, stem, exe:, image:, dlls: [])
+      members = [[exe, EXE_MODE], [image, IMAGE_MODE]] + dlls.sort_by { |d| d.basename.to_s }.map { |d| [d, DLL_MODE] }
+      members.map(&:first).each { |path| validate_member!(path) }
+      bundle = Pathname.new(dir).join(self.class.bundle_name_for(stem))
+      write_bundle(bundle, members, sums_content(members))
+      bundle
+    end
+
+    private
+
+    # SHA256SUMS, coreutils shape ("<sha>  <file>\n" per member), in member
+    # order — the bundle's last member, pinning every other (spec 36 §2).
+    def sums_content(members)
+      lines = members.map { |path, _| "#{Digest::SHA256.file(path).hexdigest}  #{path.basename}" }
+      "#{lines.join("\n")}\n"
+    end
+
+    # Deterministic bytes (spec 36 §2): fixed member order, mtime=0 in the
+    # gzip header and every tar header — identical inputs yield identical
+    # bytes, so a re-run's digest-match skip stays cheap.
+    def write_bundle(bundle, members, sums)
+      File.open(bundle, "wb") do |io|
+        gz = Zlib::GzipWriter.new(io)
+        gz.mtime = 0
+        Gem::Package::TarWriter.new(gz) do |tar|
+          members.each { |path, mode| add_member(tar, path.basename.to_s, mode, path) }
+          tar.add_file_simple(SUMS_NAME, 0o444, sums.bytesize) { |io_member| io_member.write(sums) }
+        end
+        gz.close
+      end
+    end
+
+    def add_member(tar, name, mode, path)
+      tar.add_file_simple(name, mode, path.size) do |io_member|
+        File.open(path, "rb") { |f| IO.copy_stream(f, io_member) }
+      end
+    end
+
+    # The §2 member grammar: a plain staged regular file — never a
+    # symlink, directory, or device (members are written under their bare
+    # basenames, so no path traversal is possible by construction; what
+    # remains to assert is the kind).
+    def validate_member!(path)
+      return if path.file? && !path.symlink?
+
+      raise Error, "bundle member #{path} is not a plain staged file (spec 36 §2's member grammar)"
+    end
+  end
+end

data/lib/tebako_release/config.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+# Copyright (c) 2026 [Ribose Inc](https://www.ribose.com).
+# All rights reserved.
+# This file is a part of tamatebako
+
+module TebakoRelease
+  # The consuming factory's identity: which repo's releases this run
+  # manages, the language whose version strings ride the package-name
+  # grammar, the release title prefix, the contract.yml path (the release
+  # pipeline's SSOT for the bootstrap<->runtime contract version), and the
+  # policy adapter. `repo` is the one value a sign-only consumer must
+  # declare; everything else has an upload-side default.
+  class Config
+    DEFAULT_TOOL_REPO = "tamatebako/tebako"
+
+    attr_reader :repo, :language, :title_prefix, :contract_yml, :adapter, :tool_repo
+
+    def initialize(repo:, language: nil, title_prefix: nil, contract_yml: "contract.yml", # rubocop:disable Metrics/ParameterLists
+                   adapter: Adapter.new, tool_repo: DEFAULT_TOOL_REPO)
+      @repo = repo
+      @language = language
+      @title_prefix = title_prefix || "Tebako runtime packages"
+      @contract_yml = contract_yml
+      @adapter = adapter
+      @tool_repo = tool_repo
+    end
+
+    # The minimal env-only declaration: the sign path's one repo value.
+    def self.from_env(env = ENV)
+      new(repo: env.fetch("TEBAKO_RELEASE_REPO") do
+        raise Error, "TEBAKO_RELEASE_REPO is not set and no release adapter was configured — " \
+                     "the release machinery never guesses which repo it publishes to"
+      end)
+    end
+
+    # The manifest entry's version key for this runtime's language
+    # (ruby_version / python_version / …).
+    def version_key
+      :"#{language}_version"
+    end
+
+    # The env var carrying this leg's expected version matrix
+    # (EXPECTED_RUBY_MATRIX / EXPECTED_PYTHON_MATRIX / …).
+    def version_matrix_env
+      "EXPECTED_#{language.upcase}_MATRIX"
+    end
+  end
+end

data/lib/tebako_release/error.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# Copyright (c) 2026 [Ribose Inc](https://www.ribose.com).
+# All rights reserved.
+# This file is a part of tamatebako
+
+module TebakoRelease
+  # Named error for every release-machinery failure (spec 00: named errors,
+  # never silent fallbacks).
+  class Error < StandardError; end
+end

data/lib/tebako_release/platform.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+# Copyright (c) 2026 [Ribose Inc](https://www.ribose.com).
+# All rights reserved.
+# This file is a part of tamatebako
+
+require "rbconfig"
+
+module TebakoRelease
+  # The release-side platform vocabulary: (os id, arch id) ↔ the release
+  # platform id used in runtime package names. Owned by tpkg::Platform
+  # (tamatebako/tebako, docs/spec/03 §3); NOT derivable by formula
+  # ("windows-ucrt64" carries no arch segment). windows/arm64 follows the
+  # product's RESERVED release-asset name ("windows-ucrt-arm64" — the
+  # aarch64-windows-ucrt triplet, which tpkg parses but rejects in payload
+  # manifests until the platform ships). This is the release tooling's
+  # mirror of that table; drift fails loudly in the factories' CI parity
+  # checks.
+  class Platform
+    HOST_IDS = {
+      %w[windows x86_64] => "windows-ucrt64",
+      %w[windows arm64] => "windows-ucrt-arm64",
+      %w[macos arm64] => "macos-arm64",
+      %w[macos x86_64] => "macos-x86_64",
+      %w[linux-gnu x86_64] => "linux-gnu-x86_64",
+      %w[linux-gnu arm64] => "linux-gnu-arm64",
+      %w[linux-musl x86_64] => "linux-musl-x86_64",
+      %w[linux-musl arm64] => "linux-musl-arm64"
+    }.freeze
+
+    # The lookup for callers with no detected host (the release pipeline's
+    # expected-asset model); the instance path shares the named failure.
+    def self.host_id_for(os_id, arch_id)
+      HOST_IDS.fetch([os_id, arch_id]) { raise Error, "no release platform id for #{os_id}/#{arch_id}" }
+    end
+
+    def initialize(ostype = RUBY_PLATFORM, arch = RbConfig::CONFIG["host_cpu"])
+      @ostype = ostype
+      @arch = arch
+    end
+
+    attr_reader :ostype
+
+    # Platform id as used by runtime package names (e.g. "macos-arm64",
+    # "windows-ucrt64").
+    def host_id
+      self.class.host_id_for(host_os_id, host_arch_id)
+    end
+
+    def exe_suffix
+      @ostype =~ /msys|mingw|cygwin/ ? ".exe" : ""
+    end
+
+    private
+
+    def host_os_id
+      case @ostype
+      when /msys|mingw|cygwin/ then "windows"
+      when /darwin/ then "macos"
+      when /linux-musl/ then "linux-musl"
+      when /linux/ then "linux-gnu"
+      else
+        raise Error, "no release os id for #{@ostype}"
+      end
+    end
+
+    def host_arch_id
+      case @arch
+      when /^(x86_64|amd64|x64)$/ then "x86_64"
+      when /^(aarch64|arm64)$/ then "arm64"
+      else
+        raise Error, "no release arch id for #{@arch}"
+      end
+    end
+  end
+end