Vivarium
  • 日本語

      • Vivarium Manifest v1

      外部リポジトリが .vivarium/manifest.toml に置いて Vivarium 実行可能な再現を宣言するための静的マニフェスト。

      これはアップストリームサーフェスだ——外部プロジェクトが Vivarium に 「私たちは再現をホストしている。場所はここだ」と伝える方法。 ランタイムサーフェス（DOM verdict、verdict.json）は Contract v1 で別途定義されている。

      概要

      リポジトリは以下の場所に単一の TOML ファイルを置くことで Vivarium 互換の再現を宣言できる:

      <repo-root>/.vivarium/manifest.toml
      #:schema https://aletheia-works.github.io/vivarium/spec/manifest.schema.json
manifest = "v1"
slug = "bash-local-shadows-exit"
title = "bash: `local` builtin shadows command exit code"
layer = 2

[bug]
project = "bash"
issue = 0
upstream_url = "https://lists.gnu.org/archive/html/bug-bash/"

[layer2]
image = "ghcr.io/example-org/example-bash-local-shadows-exit:latest"
dockerfile = "./Dockerfile"
expected_verdict = "reproduced"

      再現を実行したいコンシューマーはマニフェストを読み、layer でディスパッチし、 以下に定義されたレイヤーごとの規約に従う。

      スキーマディレクティブ

      Taplo や Tombi などの TOML 言語サーバを持つエディタは、 マニフェストが #:schema 行で始まる場合に manifest.toml を自動補完・検証する:

      #:schema https://aletheia-works.github.io/vivarium/spec/manifest.schema.json
manifest = "v1"
…

      このディレクティブは TOML コメントなので、プレーンパーサー（tomllib など）には 見えず、CI バリデーションはディレクティブの有無に関わらず同一の動作をする。 Cargo と pyproject マニフェストも同じパターンを使用する。

      必須トップレベルキー

      キー型注記
      manifest文字列"v1" と等しくなければならない。バージョンリテラル。
      slug文字列ケバブケース ^[a-z0-9]+(-[a-z0-9]+)*$。レシピの識別子。aletheia-works/vivarium のディレクトリ名規約に合わせる。
      layer整数1、2、3 のいずれか。必須のレイヤー固有テーブルを選択する（以下参照）。
      [bug]テーブル必須。アップストリームバグを記述。
      [bug] project文字列アップストリームプロジェクト名（例: "bash"）。
      [bug] issue整数Issue 番号。アップストリーム Issue トラッカーのエントリが存在しない場合は 0 を使用。
      [bug] upstream_url文字列（URI）Issue / メーリングリストスレッド / PR / ドキュメントページへの標準リンク。

      オプションのトップレベルキー

      キー型注記
      title文字列短い人間可読なタイトル。
      description文字列長い説明。Markdown を許可するが解釈されない。

      レイヤー固有テーブル

      [layer1]、[layer2]、[layer3] のいずれか一つが必須—— トップレベルの layer 整数と一致しなければならない。

      [layer1] — ブラウザ内 WASM

      layer = 1

[layer1]
page_url = "https://example.org/repro/some-bug/"
expected_verdict = "reproduced"  # デフォルト; オプション
      フィールド必須注記
      page_url✅静的再現ページの URL。ページは Contract v1 に準拠しなければならない。
      expected_verdict⏳"reproduced"（デフォルト）または "unreproduced"。

      [layer2] — Docker カタログ

      layer = 2

[layer2]
image = "ghcr.io/example-org/example-bash-local-shadows-exit:latest"
dockerfile = "./Dockerfile"  # オプション、情報提供のみ
expected_verdict = "reproduced"
      フィールド必須注記
      image✅コンテナイメージ参照。訪問者は docker run <image> を実行する。デフォルト CMD はレシピの再現スクリプト。終了コード 0 = バグが再現される（reproduced）。
      dockerfile⏳ソース Dockerfile へのリポジトリ相対パス。情報提供のみ——Vivarium はここからビルドしない。
      expected_verdict⏳デフォルト "reproduced"。

      [layer3] — 第三の道カタログ

      layer = 3

[layer3]
image = "ghcr.io/example-org/example-recipe:latest"
dockerfile = "./Dockerfile"
expected_verdict = "reproduced"
      フィールド必須注記
      image✅コンテナイメージ参照。
      dockerfile⏳情報提供のみ。
      expected_verdict⏳デフォルト "reproduced"。

      ⚠️ Layer 3 は Layer 1 / 2 が届かない再現——決定論的シミュレーション、 microVM スナップショットなど——のための枠。Vivarium は現在ひとつも 出荷していないので、この表は実践の記述ではなく宣言に留まる。 第三者の layer = 3 マニフェストに出会った consumer は、 ランタイム要件がそのマニフェストの作者によって文書化されていることを 期待してよい。

      Verdict セマンティクス

      expected_verdict の値は Contract v1 で ロックされた値リテラルに一致する:

      • "reproduced" ⇒ アップストリームバグが再現される。
      • "unreproduced" ⇒ アップストリームバグが再現されない。

      expected_verdict = "reproduced" を宣言するページが一般的なケースだ—— レシピはアップストリームレポートが記述した失敗を実証する。 expected_verdict = "unreproduced" を宣言するページはアップストリームの修正を 意図的に追跡するセンチネルだ。バグが再びリグレッションした瞬間に赤くなる。

      バージョニング

      バージョンはひとつの場所に記載される:

      • ドキュメントのトップの manifest = "v1"。

      フィールドの追加、削除、セマンティクスの変更には v2 マニフェスト仕様ページ、 v2 JSON Schema の兄弟ファイル、別の ADR が必要。 コンシューマーは manifest リテラルによるディスパッチで v1 と v2 を 同時サポートできるようにすべきだ。

      現在 v2 は存在しない。

      コンフォーマンス

      マニフェストが Vivarium Manifest v1 に準拠するのは:

      1. 消費リポジトリの .vivarium/manifest.toml に配置された有効な TOML 1.0 ドキュメントである。
      2. TOML→JSON 変換後に manifest.schema.json を検証パスする。
      3. [layer1] / [layer2] / [layer3] のうちちょうど一つが存在し、 トップレベルの layer 整数と一致する。
      4. 指定されたアーティファクト（ページまたはイメージ）が実際に存在し、 実行時に Contract-v1 準拠の verdict を生成する。

      条項 1〜3 はスキーマバリデーションで機械的に強制できる。条項 4 はレシピごとの検証だ。

      リファレンス実装

      aletheia-works/vivarium リポジトリは src/external_examples/ 以下にレイヤーごとに 3 つのサンプルマニフェストを出荷している——すべて Vivarium 自身の 公開デプロイページと GHCR イメージを指しているため、形だけ有効なのではなく実際に 実行可能なものとして書かれている。

      repro-regression.yml の CI は、毎回のプッシュとプルリクエストで src/external_examples/*/.vivarium/manifest.toml をすべてこのスキーマに対して検証する。

      関連情報

      • Contract v1 — このマニフェストが指すアーティファクトが公開しなければならないランタイム verdict サーフェス。
      • manifest.schema.json — TOML→JSON 変換後のマニフェスト用 JSON Schema（draft 2020-12）。
      • Consumer workflow — コンシューマーが自身の CI でマニフェストで宣言されたイメージを検証するための再利用可能 GitHub Actions ワークフロー。