yoi/item.md at 8b7a5da03130f4453b2c5857504b3c7839401e07

Hare/yoi

Fork 0

Hare 3cee4116d1

ticket: plan execution workspace materializer

2026-07-07 03:27:12 +09:00

16 KiB

Raw Blame History

title

state

created_at

updated_at

linked_tickets

Runtime execution workspace materialization and sandboxed agent environments

active

2026-07-06T16:28:12Z

00001KWPC13WQ

00001KWMBAA6V

Goal

Runtime が Worker ごとに安全で安価な作業環境を用意できるようにする。Yoi の Runtime は、単に既存ディレクトリで Worker process を起動する launcher ではなく、RepositoryPoint から Execution Workspace を materialize し、sandbox / mount / cache / cleanup / evidence を管理する実行基盤になる。

この Objective の中心は、Worktree ライクな作業ディレクトリ管理、Repository cache、Execution Workspace allocation、sandboxed agent environment の境界を設計し、将来的に 1 つの Runtime が複数 Workspace / Repository の Worker を抱えられるようにすることである。

初期実装では Git/local repository を主対象にしてよい。ただし設計は Git worktree 固定にしない。Git worktree、bare object cache、sparse checkout、copy-on-write snapshot、reflink copy、APFS clonefile、btrfs snapshot、overlay filesystem、container filesystem、remote object snapshot は、すべて Execution Workspace materialization strategy の候補として扱う。

Motivation / background

現在の Runtime は --workspace で与えられた単一 root を Worker の workspace scope として使う。この形では次の問題がある。

複数 Worker が同じ repository root を scope として要求すると allocation conflict が起きる。
Runtime が single Workspace / Git repository root 専用 process になってしまう。
Worker が source repository root を直接触るため、sandbox / cleanup / quota / evidence の境界が曖昧になる。
Worker ごとに full clone すると容量と時間のコストが大きすぎる。
.yoi / Backend fs-store / Workspace descriptor と、Worker 実行用 checkout / scratch / build output の lifecycle が混ざりやすい。

Yoi は Workspace / Repository / Runtime を分ける方針になっている。Backend は Repository registry、RepositorySelector、RepositoryPoint、Ticket/Artifact evidence の authority を持つ。一方 Runtime は RepositoryPoint を受け取り、Worker が使う Execution Workspace を用意する責務を持つべきである。

したがって、Repository を持ってくる実体ディレクトリは Backend / Workspace store ではなく Runtime 管理領域に置く。./.yoi は local descriptor / compatibility / project record surface であり、Worker ごとの checkout、worktree、snapshot、sandbox root、build cache、dependency cache を置く場所ではない。

参考になる方向性として、Rift のような copy-on-write workspace snapshot / reflink / btrfs snapshot / APFS clonefile による安価な workspace creation がある。ただし Yoi は Rift を Git worktree 代替 CLI として直接前提にするのではなく、Runtime materializer backend の一候補として扱う。

Glossary

Runtime root: Runtime が自身の store、cache、Worker metadata、Execution Workspace allocation を管理する root。長期的には ~/.yoi/runtimes/<runtime-id>/ 配下など、Workspace backend store とは別に置く。
Repository cache: Runtime-local の共有 source/cache。Git なら bare mirror / object cache / packfile cache など。重く、長寿命で、複数 Worker allocation から共有される。
Execution Workspace: Worker ごとの作業環境。短寿命で、Worker が読み書きする root / mounts / scratch / overlay を含む。
Materialization strategy: RepositoryPoint から Execution Workspace を作る実装戦略。Git detached worktree、sparse checkout、CoW snapshot、reflink copy、overlay、container filesystem など。
ExecutionWorkspaceAllocation: Runtime が払い出した作業環境の record。allocation id、worker id、workspace id、repository point、materializer kind、root、mounts、cleanup policy、status を持つ。
Sandbox policy: Worker が見られる filesystem、network、process、secret、tool authority の境界を表す policy。
Dirty state policy: local uncommitted changes を Worker environment に含めるかどうかの方針。clean point only、patch artifact apply、snapshot current worktree など。

Strategy / design direction

1. Backend store と Runtime execution storage を分ける

Workspace/backend store は canonical or local descriptor records を扱う。

Backend / Control plane store
  - Workspace registry
  - Repository registry
  - Ticket / Objective
  - Artifact metadata / evidence
  - Actor / Permission / Audit
  - Runtime registry / observed state

Runtime execution storage は Worker 実行のための materialized filesystem と cache を扱う。

Runtime root
  - runtime catalog / runtime-local DB
  - config bundles
  - worker metadata / transcript references
  - repository-cache
  - execution-workspaces
  - sandbox state
  - build/dependency cache
  - cleanup ledger

この 2 つを混ぜない。特に .yoi や workspace config root に Worker ごとの checkout/worktree/sandbox root を置かない。

推奨配置の方向:

~/.yoi/
  workspace-server/
    backend.db
    workspaces/
      <workspace-id>/
        workspace.db
        artifacts/

  runtimes/
    <runtime-id>/
      runtime.db
      config-bundles/
      workers/
        <worker-id>/
          metadata/
      repository-cache/
        git/
          <repository-cache-key>/
            bare.git
      execution-workspaces/
        <allocation-id>/
          root/
          mounts/
          scratch/
          materialization.json
      build-cache/
      tmp/

2. clone ではなく materialize と呼ぶ

Runtime は Repository を毎回 clone するのではない。Runtime は RepositoryPoint を Worker 用の Execution Workspace として materialize する。

RepositoryId + RepositorySelector
  -> resolved RepositoryPoint
  -> Runtime repository-cache
  -> ExecutionWorkspaceMaterializer
  -> ExecutionWorkspaceAllocation
  -> Worker process

Git の場合でも materialization strategy は複数あり得る。

shared bare cache + detached Git worktree
sparse checkout
partial clone / blob filter
reflink copy
btrfs writable snapshot
APFS clonefile
overlay filesystem
external tool backed snapshot, e.g. Rift-like CoW workspace creation

3. Repository cache と Worker workspace を分離する

full clone を Worker ごとに作らない。重い source/object data は Runtime-local repository cache に集約し、Worker ごとの Execution Workspace は cheap allocation にする。

Git v0 の方向:

repository-cache/git/<repo-key>/bare.git
execution-workspaces/<allocation-id>/root/<repository-id>/

初回:

git clone --mirror <uri> repository-cache/git/<repo-key>/bare.git

次回以降:

git -C repository-cache/git/<repo-key>/bare.git fetch --prune

Worker allocation:

git --git-dir=<bare.git> worktree add --detach <execution-root>/<repository-id> <commit>

Git branch 名を直接 checkout しない。Git worktree は同一 branch を複数 worktree に checkout しづらいため、RepositorySelector を RepositoryPoint に解決し、resolved commit を detached worktree として materialize する。Worker が branch を必要とする場合は Worker/Task ごとの synthetic branch を別途作る。

4. Dirty state を明示 policy にする

local dirty changes を暗黙に Worker に見せない。

可能な policy:

clean_point_only: dirty workspace は materialization 拒否。再現性が高く v0 の default 候補。
patch_artifact: clean RepositoryPoint を materialize し、Backend が保存した dirty diff artifact を apply する。
current_worktree_snapshot: CoW/reflink/Rift-like snapshot で現在の working tree を snapshot として materialize する。便利だが evidence と cleanup の扱いを明示する必要がある。
direct_legacy_mount: 既存 root をそのまま渡す。debug/legacy only。通常 Worker creation の default にしない。

Dirty state を含める場合、Artifact/evidence には source RepositoryPoint、patch/snapshot digest、created_at、materializer kind を残す。

5. Sandbox を materialization と同じ境界で扱う

Execution Workspace は単なる directory path ではなく、Worker が見てよい filesystem view である。Runtime は Execution Workspace allocation と同時に sandbox/mount/authority を構築する。

Worker に渡すもの:

workspace root
repository mounts
scratch/cache dirs
tool authority
env vars
config bundle
secret handles, not raw secrets

Worker が自分で発見してはいけないもの:

host repository root
Backend store path
.yoi authority-bearing internals
raw credentials
Runtime socket/store/cache internals
sibling Worker workspaces

Sandbox v0 は strong isolation でなくてもよい。ただし型と lifecycle は、後で container sandbox、namespace, mount filtering, network policy, secret boundary に拡張できる形にする。

6. Execution Workspace registry を持つ

Runtime は materialized workspace を filesystem だけでなく registry でも管理する。

必要な record:

ExecutionWorkspaceAllocation
  id
  runtime_id
  worker_id
  workspace_id
  repository_points[]
  materializer_kind
  root
  mounts[]
  scratch
  source_cache_refs[]
  sandbox_policy
  dirty_state_policy
  cleanup_policy
  status: active | stopped | cleanup_pending | removed | failed
  created_at
  stopped_at
  diagnostics[]

この registry は Runtime root 側に置く。Backend は必要な evidence と summary だけを受け取る。Browser-facing API は raw host paths を原則漏らさない。

7. Heavy regenerable artifacts は policy で除外または cache 化する

Worker workspace creation では、node_modules, target, .venv, framework cache, dist, build, coverage などを無条件に full copy しない。

Materialization policy は以下を持てるようにする。

exclude regenerable artifacts
include manifests / lockfiles
share dependency cache
use build cache
path scope / sparse checkout
per-repository materialization options

Rift の filtered CoW creation のように、重い artifacts を除外しながら source tree を高速に用意できる strategy を将来取り込めるようにする。

Initial implementation phases

Phase 1: Materialization boundary and legacy allocation record

CreateWorkerRequest に Execution Workspace request / target placeholder を追加する。
ExecutionWorkspaceMaterializer trait を worker-runtime に追加する。
WorkerRuntimeExecutionBackend が Worker spawn 前に materializer を呼ぶ順序にする。
v0 materializer は existing local root を explicit allocation として返してよいが、direct_legacy_mount として明示し、通常設計の final form と混同しない。
Allocation record / cleanup policy / diagnostics の型を先に作る。
Worker が source repository root を直接 scope として要求する経路を deprecated/legacy に閉じ込める。

Phase 2: Runtime root and execution workspace storage

--runtime-root を導入し、Runtime state / repository-cache / execution-workspaces / worker metadata / worker runtime dirs を Runtime root 配下へ寄せる。
--workspace は legacy bootstrap input としてだけ扱い、Runtime identity / long-term workspace binding から外す。
Runtime root default は user data 配下にする。
Execution Workspace allocation registry を Runtime root に保存する。

Phase 3: Git cached detached worktree materializer

Git repository cache を Runtime root に作る。
RepositorySelector を RepositoryPoint に解決する呼び出し境界を作る。
resolved commit/tree を evidence として残す。
Worker ごとに detached worktree を execution-workspaces/<allocation-id>/root/<repository-id> に作る。
Worker stop / cleanup 時に git worktree remove と registry cleanup を行う。
dirty state は v0 では clean_point_only を default にし、dirty local workspace は明示 diagnostic で拒否する。

Phase 4: Path scope / sparse checkout / cache policies

Ticket target / Worker launch request の path scope を materialization に渡す。
Git sparse checkout を materializer strategy として追加する。
heavy artifact exclude / dependency cache / build cache policy を導入する。

Phase 5: CoW / snapshot materializer

btrfs snapshot、Linux reflink、macOS APFS clonefile、Rift-like snapshot backend を materializer strategy として検討・実装する。
current_worktree_snapshot policy を evidence と cleanup 付きで扱う。
source root と generated workspace の registry / ancestor / cleanup model を設計する。

Phase 6: Strong sandbox and remote Runtime support

container filesystem / mount namespace / network policy / secret handle / tool authority を Runtime allocation と統合する。
Runtime が複数 Workspace / Repository の Worker を同時に抱える場合の namespace、quota、cleanup、audit boundary を固める。
remote/self-hosted/hosted Runtime fleet で repository cache と execution workspace storage をどう扱うかを設計する。

Non-goals

v0 で完全な container sandbox を実装すること。
Worker ごとに full clone すること。
.yoi や Backend workspace store に Worker execution workspace を置くこと。
Git worktree を唯一の materialization strategy として固定すること。
Dirty local changes を暗黙に Worker に渡すこと。
Browser-facing API に raw host path、secret、Runtime internal store path を公開すること。
Repository credential / secret distribution の本格設計をこの Objective だけで完了させること。

Success criteria / exit conditions

Runtime root、Repository cache、Execution Workspace、Backend/Workspace store の境界が文書化されている。
Runtime が Worker spawn 前に Execution Workspace materializer を呼ぶ型と順序を持つ。
Worker は source repository root ではなく materialized Execution Workspace を scope として起動する。
Execution Workspace allocation が Runtime registry に記録され、cleanup policy を持つ。
Git/local repository の v0 materializer が full clone 連発ではなく shared cache / detached worktree / cheap allocation の方向に進んでいる。
dirty state policy が明示され、clean point、patch artifact、snapshot のどれを使ったか evidence に残せる。
Runtime process 起動時の --workspace は legacy bootstrap input として隔離され、Runtime identity や single workspace binding とみなされない。
Worker ごとの scope allocation conflict が、同一 source root を直接渡す設計ではなく materialized workspace allocation によって解消される。
Sandbox / mount / cache / secret boundary を後続実装で強化できる model になっている。

References

Rift: Worktree alternative for fast copy-on-write workspaces — CoW snapshot / reflink / btrfs snapshot / APFS clonefile による高速 workspace creation、heavy regenerable artifacts の除外、workspace registry などを Runtime materializer backend 設計の参考にする。

Decision context

Runtime は Worker 群を束ねる実行基盤であり、Worker 用の作業環境を用意する責務を持つ。
Repository は clone されるものではなく、RepositoryPoint から Worker 用 Execution Workspace として materialize される。
Runtime execution storage は Backend/Workspace store と分離する。.yoi は Worker execution workspace 置き場ではない。
full clone を Worker ごとに作らない。Runtime-local repository cache と Worker-local cheap workspace allocation を分ける。
Git detached worktree は v0 materialization strategy として有力だが、Git worktree 固定の設計にはしない。
CoW snapshot / reflink / btrfs snapshot / APFS clonefile / Rift-like workspace creation は、将来の materializer backend として検討する。
Dirty local state は暗黙に渡さず、policy と evidence を持って扱う。
Sandbox は後付けの別機能ではなく、Execution Workspace allocation と同じ境界で扱う。

16 KiB Raw Blame History