objective: clarify working directory terminology

This commit is contained in:
Keisuke Hirata 2026-07-07 23:41:27 +09:00
parent 9f1c17d4e9
commit a6b93ceabc
No known key found for this signature in database
2 changed files with 58 additions and 58 deletions

View File

@ -2,7 +2,7 @@
title: "Team workspace control plane and runtime architecture" title: "Team workspace control plane and runtime architecture"
state: "active" state: "active"
created_at: "2026-06-20T14:26:29Z" created_at: "2026-06-20T14:26:29Z"
updated_at: "2026-07-03T18:05:00Z" updated_at: "2026-07-07T12:40:00Z"
linked_tickets: ["00001KVMFFYVX", "00001KWMBAA6V"] linked_tickets: ["00001KVMFFYVX", "00001KWMBAA6V"]
--- ---
@ -20,14 +20,14 @@ Yoi を、単一のローカル開発ディレクトリで動くエージェン
- Workspace: チームまたはプロジェクトの管理単位。Ticket、Objective、Memory、Knowledge、Artifact、Policy、Actor、Repository、Runtime state を持つ。Git Repository root ではない。 - Workspace: チームまたはプロジェクトの管理単位。Ticket、Objective、Memory、Knowledge、Artifact、Policy、Actor、Repository、Runtime state を持つ。Git Repository root ではない。
- Control plane: Workspace の正本を持ち、Web UI / API / CLI から操作される管理システム。 - Control plane: Workspace の正本を持ち、Web UI / API / CLI から操作される管理システム。
- Runtime: Worker 群を束ねる実行基盤。Worker lifecycle、sandbox、mount、cache、checkout/worktree/container filesystem などの Execution Workspace materialization、event/control plane を管理する。将来的には 1 つの Runtime が複数 Workspace / Repository の Worker を抱えられる。 - Runtime: Worker 群を束ねる実行基盤。Worker lifecycle、sandbox、mount、cache、checkout/worktree/container filesystem などの working directory materialization、event/control plane を管理する。将来的には 1 つの Runtime が複数 Workspace / Repository の Worker を抱えられる。
- Worker: Runtime が管理する 1 つの agent/session/process。Runtime が用意した Execution Workspace と authority の中で動く。 - Worker: Runtime が管理する 1 つの agent/session/process。Runtime が用意した working directory と authority の中で動く。
- Repository: Workspace に接続される source/storage。コード、ドキュメント、local directory、object storage、artifact store、dataset などを含む。Git Repository も Repository の一種であり、基本的には filesystem path ではなく URI / URL で識別する。 - Repository: Workspace に接続される source/storage。コード、ドキュメント、local directory、object storage、artifact store、dataset などを含む。Git Repository も Repository の一種であり、基本的には filesystem path ではなく URI / URL で識別する。
- RepositoryId: Workspace 内でどの Repository を対象にするかを指す安定 identifier。Git hash、branch、path ではない。 - RepositoryId: Workspace 内でどの Repository を対象にするかを指す安定 identifier。Git hash、branch、path ではない。
- Repository provider: Repository の種類ごとの実装。Git、local filesystem、object store、artifact store、将来の non-Git VCS など。 - Repository provider: Repository の種類ごとの実装。Git、local filesystem、object store、artifact store、将来の non-Git VCS など。
- RepositorySelector: Repository provider に渡す未解決の地点指定。branch/tag/PR/revspec/bookmark/revset/path@revision/object version/latest など provider-specific な symbolic / mutable / query-like locator であり、それ自体は再現性の authority ではない。 - RepositorySelector: Repository provider に渡す未解決の地点指定。branch/tag/PR/revspec/bookmark/revset/path@revision/object version/latest など provider-specific な symbolic / mutable / query-like locator であり、それ自体は再現性の authority ではない。
- RepositoryPoint: RepositorySelector をある時点で解決した具体地点。Git commit/tree、Mercurial changeset、SVN revision、object store version/manifest digest、file snapshot など provider ごとの immutable / reproducible point を表し、Artifact/evidence に残す。 - RepositoryPoint: RepositorySelector をある時点で解決した具体地点。Git commit/tree、Mercurial changeset、SVN revision、object store version/manifest digest、file snapshot など provider ごとの immutable / reproducible point を表し、Artifact/evidence に残す。
- Execution Workspace: Runtime が Worker のために作る作業環境。1 つ以上の RepositoryPoint から materialize される作業用ディレクトリ、container filesystem、sandbox mount の集合であり、Git worktree、clone、sparse checkout などはこれを作る手段である。 - working directory: Runtime が Worker のために作る作業環境。1 つ以上の RepositoryPoint から materialize される作業用ディレクトリ、container filesystem、sandbox mount の集合であり、Git worktree、clone、sparse checkout などはこれを作る手段である。Browser-facing UI/API では product `Workspace` と混同しないよう、この呼称に寄せる。`Volume` は storage backing の候補名に留め、作業領域そのものの呼称にはしない。
- Ticket: チームで扱う作業単位。目的、要件、判断、議論、完了条件、関係、証跡を持つ。 - Ticket: チームで扱う作業単位。目的、要件、判断、議論、完了条件、関係、証跡を持つ。
- Objective: 複数の Ticket を束ねる長期目標や設計方針。 - Objective: 複数の Ticket を束ねる長期目標や設計方針。
- Artifact: Ticket や Worker 実行に紐づく成果物や証跡。diff、log、validation result、review result、report など。 - Artifact: Ticket や Worker 実行に紐づく成果物や証跡。diff、log、validation result、review result、report など。
@ -46,7 +46,7 @@ Yoi を、単一のローカル開発ディレクトリで動くエージェン
- 管理システムと Runtime を分ける。 - 管理システムと Runtime を分ける。
- まず Web から Ticket、Objective、Memory、Knowledge、Artifact、Runtime / Worker state を見られるようにする。 - まず Web から Ticket、Objective、Memory、Knowledge、Artifact、Runtime / Worker state を見られるようにする。
- 最初はローカル Runtime を使い、後でリモート Runtime、クラウド Runtime、runtime pool、resource allocation、quota、billing、sandboxing に拡張する。 - 最初はローカル Runtime を使い、後でリモート Runtime、クラウド Runtime、runtime pool、resource allocation、quota、billing、sandboxing に拡張する。
- Git ホスティング機能を取り込むのではなく、Git Repository / worktree / clone は Repository provider と Execution Workspace materialization の手段として扱う。 - Git ホスティング機能を取り込むのではなく、Git Repository / worktree / clone は Repository provider と working directory materialization の手段として扱う。
OSS として Control plane、Runtime、Web frontend、protocol を公開しつつ、managed service では hosted control plane、runtime fleet、リソース柔軟性、team auth、backup、audit、availability、multi-tenant operations で価値を出す。 OSS として Control plane、Runtime、Web frontend、protocol を公開しつつ、managed service では hosted control plane、runtime fleet、リソース柔軟性、team auth、backup、audit、availability、multi-tenant operations で価値を出す。
@ -68,7 +68,7 @@ Ticket と Objective は Repository 配下に置かず、Workspace 配下に平
RepositorySelector は Git branch/tag の抽象化ではない。Selector は provider-specific な未解決 locator であり、Git provider なら branch/tag/ref/revspec/PR/commit、Mercurial provider なら bookmark/revset/changeset、SVN provider なら path/revision、object store provider なら prefix/version/latest などを解釈する。実行時には Control plane または Repository provider が Selector を RepositoryPoint に解決し、Runtime はその RepositoryPoint を materialize する。 RepositorySelector は Git branch/tag の抽象化ではない。Selector は provider-specific な未解決 locator であり、Git provider なら branch/tag/ref/revspec/PR/commit、Mercurial provider なら bookmark/revset/changeset、SVN provider なら path/revision、object store provider なら prefix/version/latest などを解釈する。実行時には Control plane または Repository provider が Selector を RepositoryPoint に解決し、Runtime はその RepositoryPoint を materialize する。
Worker launch request は Ticket の target selector を concrete RepositoryPoint に解決し、その RepositoryPoint から Runtime が Execution Workspace を materialize する。Git worktree 相当の機能は、この Execution Workspace を作るための実装戦略として扱う。 Worker launch request は Ticket の target selector を concrete RepositoryPoint に解決し、その RepositoryPoint から Runtime が working directory を materialize する。Git worktree 相当の機能は、この working directory を作るための実装戦略として扱う。
Backend は cwd や `--workspace` を暗黙の Repository として扱わない。`--workspace` は当面 workspace config root / local descriptor root を指すだけであり、Repository registry は明示設定された Workspace config から構築する。短期的には `.yoi/workspace-backend.local.toml``[[repositories]]` を local descriptor として使い、`uri = "."` のような local repository も明示 entry として登録する。`./` を暗黙 Repository として自動採用しない。 Backend は cwd や `--workspace` を暗黙の Repository として扱わない。`--workspace` は当面 workspace config root / local descriptor root を指すだけであり、Repository registry は明示設定された Workspace config から構築する。短期的には `.yoi/workspace-backend.local.toml``[[repositories]]` を local descriptor として使い、`uri = "."` のような local repository も明示 entry として登録する。`./` を暗黙 Repository として自動採用しない。
@ -86,7 +86,7 @@ Ticket target は intent/selector であり、実行再現性のための immuta
Ticket Ticket
-> target selectors: Repository + ref selector + path + intent -> target selectors: Repository + ref selector + path + intent
-> resolved RepositoryPoint -> resolved RepositoryPoint
-> Execution Workspace -> working directory
-> WorkerRef / Artifact / Evidence -> WorkerRef / Artifact / Evidence
-> Review / Decision -> Review / Decision
-> Audit / Notification -> Audit / Notification
@ -119,7 +119,7 @@ Ticket には次の概念が必要になる。
- Actor identity: human / agent / system / service account. - Actor identity: human / agent / system / service account.
- Assignment / owner / reviewer / watcher. - Assignment / owner / reviewer / watcher.
- Typed thread events: comment, decision, plan, review, implementation report, state transition. - Typed thread events: comment, decision, plan, review, implementation report, state transition.
- Linked Objective / Artifact / WorkerRef / Repository / RepositoryPoint / Execution Workspace. - Linked Objective / Artifact / WorkerRef / Repository / RepositoryPoint / working directory.
- Permission / visibility. - Permission / visibility.
- Audit trail. - Audit trail.
- Notification / mention. - Notification / mention.
@ -170,17 +170,17 @@ Ticket / user intent
-> RepositoryId + RepositorySelector + path scope + required authority -> RepositoryId + RepositorySelector + path scope + required authority
-> resolved RepositoryPoint -> resolved RepositoryPoint
-> WorkerLaunchRequest / ConfigBundle / AuthorityBundle -> WorkerLaunchRequest / ConfigBundle / AuthorityBundle
-> Runtime ExecutionWorkspaceMaterializer -> Runtime WorkingDirectoryMaterializer
-> Execution Workspace allocation -> working directory allocation
-> Worker process -> Worker process
-> WorkerRef + Artifact/evidence -> WorkerRef + Artifact/evidence
``` ```
Control plane は Workspace authority、Ticket target、Repository registry、Actor permission、設定 bundle の正本を持つ。Control plane または Repository provider は RepositorySelector を RepositoryPoint に解決し、どの地点を対象にしたかを evidence に残す。Runtime は RepositoryPoint、materialization policy、sandbox policy、mount/cache/secret policy、Worker config を受け取り、Runtime-local な Execution Workspace を確保して Worker を起動する。 Control plane は Workspace authority、Ticket target、Repository registry、Actor permission、設定 bundle の正本を持つ。Control plane または Repository provider は RepositorySelector を RepositoryPoint に解決し、どの地点を対象にしたかを evidence に残す。Runtime は RepositoryPoint、materialization policy、sandbox policy、mount/cache/secret policy、Worker config を受け取り、Runtime-local な working directory を確保して Worker を起動する。
この境界では、Worker は host filesystem path や Repository credential を自分で発見しない。Worker は Runtime が materialize した workspace root、mount、環境変数、tool authority、config bundle だけを見る。Runtime は Execution Workspace の lifecycle、cleanup、cache reuse、namespace、quota、sandbox boundary、event collection を管理する。Control plane / Browser-facing API は raw host path、secret、socket、internal runtime path を authority-bearing internals として扱い、必要な evidence だけを Artifact として公開する。 この境界では、Worker は host filesystem path や Repository credential を自分で発見しない。Worker は Runtime が materialize した working directory root、mount、環境変数、tool authority、config bundle だけを見る。Runtime は working directory の lifecycle、cleanup、cache reuse、namespace、quota、sandbox boundary、event collection を管理する。Control plane / Browser-facing API は raw host path、secret、socket、internal runtime path を authority-bearing internals として扱い、必要な evidence だけを Artifact として公開する。
v0 materializer は existing local root を明示的な Execution Workspace として返してよい。ただし型と呼び出し順序は、後で Git worktree、clone、sparse checkout、container filesystem、remote object snapshot、multi-repository mount に置き換えられる形にする。Runtime process 起動時の `--workspace` はこの v0 materializer の legacy bootstrap input であり、Runtime identity や long-term workspace binding ではない。 v0 materializer は existing local root を明示的な working directory として返してよい。ただし型と呼び出し順序は、後で Git worktree、clone、sparse checkout、container filesystem、remote object snapshot、multi-repository mount に置き換えられる形にする。Runtime process 起動時の `--workspace` はこの v0 materializer の legacy bootstrap input であり、Runtime identity や long-term workspace binding ではない。
その後で、remote Runtime、self-hosted Runtime、hosted cloud runtime fleet、runtime pool、resource allocation、quota、billing、sandbox、network policy、secret distribution を追加する。 その後で、remote Runtime、self-hosted Runtime、hosted cloud runtime fleet、runtime pool、resource allocation、quota、billing、sandbox、network policy、secret distribution を追加する。
@ -204,7 +204,7 @@ Web UI は Ticket、Objective、Memory、Knowledge、Runtime、Worker、Artifact
### 7. 多重起動コストと runtime placement を見直す ### 7. 多重起動コストと runtime placement を見直す
Cloud/remote execution を成立させるには、多数のエージェント実行を安く管理できる必要がある。logical Worker session と Runtime process/resource placement を分ける。Runtime は Git Repository root や Workspace path に固定されず、request ごとに必要な Execution Workspace を materialize できる実行基盤として扱う。 Cloud/remote execution を成立させるには、多数のエージェント実行を安く管理できる必要がある。logical Worker session と Runtime process/resource placement を分ける。Runtime は Git Repository root や Workspace path に固定されず、request ごとに必要な working directory を materialize できる実行基盤として扱う。
初期 Workspace DB では、Worker を canonical table として永続化しない。Runtime / Worker 一覧は backend-local runtime inspection や将来の Runtime protocol から逐次取得する live view とし、Ticket に関わった Worker は Ticket thread events と WorkerRef snapshot / TicketWorkerLink として記録する。 初期 Workspace DB では、Worker を canonical table として永続化しない。Runtime / Worker 一覧は backend-local runtime inspection や将来の Runtime protocol から逐次取得する live view とし、Ticket に関わった Worker は Ticket thread events と WorkerRef snapshot / TicketWorkerLink として記録する。
@ -214,7 +214,7 @@ Worker の一元管理、データ永続化、アーカイブは将来的には
- Worker identity と Runtime process/resource placement の分離。 - Worker identity と Runtime process/resource placement の分離。
- 1 Runtime が複数 Workspace / Repository の Worker を抱える場合の namespace、quota、cleanup、audit boundary。 - 1 Runtime が複数 Workspace / Repository の Worker を抱える場合の namespace、quota、cleanup、audit boundary。
- Runtime-side Execution Workspace materialization、sandbox、mount、checkout/worktree/container filesystem の責務。 - Runtime-side working directory materialization、sandbox、mount、checkout/worktree/container filesystem の責務。
- Provider client、tool registry、resource cache の共有可能性。 - Provider client、tool registry、resource cache の共有可能性。
- Prompt/resource/profile/config bundle resolution cache。 - Prompt/resource/profile/config bundle resolution cache。
- Model call multiplexing and scheduling。 - Model call multiplexing and scheduling。
@ -226,7 +226,7 @@ Worker の一元管理、データ永続化、アーカイブは将来的には
## Initial phases / candidate tickets ## Initial phases / candidate tickets
1. **Vocabulary / architecture record** 1. **Vocabulary / architecture record**
- Workspace / RepositoryId / RepositorySelector / RepositoryPoint / Execution Workspace / Runtime / Worker / Control Plane / Ticket / Memory / Knowledge の用語と境界を固める。 - Workspace / RepositoryId / RepositorySelector / RepositoryPoint / working directory / Runtime / Worker / Control Plane / Ticket / Memory / Knowledge の用語と境界を固める。
2. **Team-space canonical data model** 2. **Team-space canonical data model**
- Ticket / Objective / Target / Artifact / Actor / Permission / Audit / Memory / Knowledge の entity/event model を設計する。 - Ticket / Objective / Target / Artifact / Actor / Permission / Audit / Memory / Knowledge の entity/event model を設計する。
3. **Ticket evidence model** 3. **Ticket evidence model**
@ -238,8 +238,8 @@ Worker の一元管理、データ永続化、アーカイブは将来的には
6. **Web control plane MVP design** 6. **Web control plane MVP design**
- read-only Ticket / Objective / Memory / Knowledge / Runtime / Worker state UI/API の範囲を決める。 - read-only Ticket / Objective / Memory / Knowledge / Runtime / Worker state UI/API の範囲を決める。
7. **Local Runtime protocol design** 7. **Local Runtime protocol design**
- Web/control plane から local Runtime に安全な操作を送り、Runtime が Worker lifecycle と Execution Workspace materialization を担う protocol と authority boundary を設計する。 - Web/control plane から local Runtime に安全な操作を送り、Runtime が Worker lifecycle と working directory materialization を担う protocol と authority boundary を設計する。
8. **Repository and Execution Workspace materialization model** 8. **Repository and working directory materialization model**
- Repository URI、Repository provider capability、RepositorySelector resolution、RepositoryPoint evidence、Git worktree / clone / sparse checkout / future source backend を Runtime-side materialization strategy として抽象化する。 - Repository URI、Repository provider capability、RepositorySelector resolution、RepositoryPoint evidence、Git worktree / clone / sparse checkout / future source backend を Runtime-side materialization strategy として抽象化する。
9. **Remote/hosted runtime foundation** 9. **Remote/hosted runtime foundation**
- runtime registration, heartbeat, capability advertisement, job assignment, logs/events, secrets, sandbox/resource policy を設計する。 - runtime registration, heartbeat, capability advertisement, job assignment, logs/events, secrets, sandbox/resource policy を設計する。
@ -258,7 +258,7 @@ Worker の一元管理、データ永続化、アーカイブは将来的には
## Success criteria / exit conditions ## Success criteria / exit conditions
- Workspace / RepositoryId / RepositorySelector / RepositoryPoint / Execution Workspace / Runtime / Worker / Control Plane / Ticket / Memory / Knowledge の境界が文書化されている。 - Workspace / RepositoryId / RepositorySelector / RepositoryPoint / working directory / Runtime / Worker / Control Plane / Ticket / Memory / Knowledge の境界が文書化されている。
- Ticket が team coordination record として、target selector / Artifact / Actor / Permission / Audit と分離された model を持つ。 - Ticket が team coordination record として、target selector / Artifact / Actor / Permission / Audit と分離された model を持つ。
- `.yoi` local backend は compatibility/local backend として整理され、server-side canonical backend の設計を阻害しない。 - `.yoi` local backend は compatibility/local backend として整理され、server-side canonical backend の設計を阻害しない。
- Web UI/API が Ticket / Objective / Runtime / Worker state を中心とした read-only view を提供できる設計または MVP を持つ。Memory / Knowledge は既存 record の表示または将来 placeholder に留め、本格再設計をこの段階の必須条件にしない。 - Web UI/API が Ticket / Objective / Runtime / Worker state を中心とした read-only view を提供できる設計または MVP を持つ。Memory / Knowledge は既存 record の表示または将来 placeholder に留め、本格再設計をこの段階の必須条件にしない。
@ -266,7 +266,7 @@ Worker の一元管理、データ永続化、アーカイブは将来的には
- Runtime は single Workspace / Git repository root 専用 process ではなく、sandbox/authority が成立すれば複数 Workspace / Repository の Worker を抱えられる execution substrate として設計されている。 - Runtime は single Workspace / Git repository root 専用 process ではなく、sandbox/authority が成立すれば複数 Workspace / Repository の Worker を抱えられる execution substrate として設計されている。
- Git Repository root に依存しない Workspace model があり、Git Repository は Repository provider の一種として扱われている。 - Git Repository root に依存しない Workspace model があり、Git Repository は Repository provider の一種として扱われている。
- Ticket と Objective は Workspace 配下に平たく存在し、Repository への所属ではなく RepositoryId / RepositorySelector / path scope / intent で対象を表現する。 - Ticket と Objective は Workspace 配下に平たく存在し、Repository への所属ではなく RepositoryId / RepositorySelector / path scope / intent で対象を表現する。
- Git worktree 相当は Execution Workspace materialization strategy として扱われ、Artifact/evidence が concrete RepositoryPoint を記録する。 - Git worktree 相当は working directory materialization strategy として扱われ、Artifact/evidence が concrete RepositoryPoint を記録する。
- Memory / Knowledge は Ticket / Artifact の authority を置き換えない record として platform contract だけを持つ。本格的な意味論・抽出・承認・検索・staleness 処理は、Memory の保存先を Workspace backend / control plane record に移すタイミングで回収する。 - Memory / Knowledge は Ticket / Artifact の authority を置き換えない record として platform contract だけを持つ。本格的な意味論・抽出・承認・検索・staleness 処理は、Memory の保存先を Workspace backend / control plane record に移すタイミングで回収する。
- Hosted Runtime / resource allocation / SaaS offering に進むための後続 Ticket が切れる状態になっている。 - Hosted Runtime / resource allocation / SaaS offering に進むための後続 Ticket が切れる状態になっている。
- 既存 local dogfooding runtime を壊さず、local use と remote-capable architecture が両立している。 - 既存 local dogfooding runtime を壊さず、local use と remote-capable architecture が両立している。

View File

@ -1,18 +1,18 @@
--- ---
title: "Runtime execution workspace materialization and sandboxed agent environments" title: "Runtime working directory materialization and sandboxed agent environments"
state: "active" state: "active"
created_at: "2026-07-06T16:28:12Z" created_at: "2026-07-06T16:28:12Z"
updated_at: "2026-07-06T16:28:12Z" updated_at: "2026-07-07T12:40:00Z"
linked_tickets: ["00001KWPC13WQ", "00001KWMBAA6V"] linked_tickets: ["00001KWPC13WQ", "00001KWMBAA6V"]
--- ---
## Goal ## Goal
Runtime が Worker ごとに安全で安価な作業環境を用意できるようにする。Yoi の Runtime は、単に既存ディレクトリで Worker process を起動する launcher ではなく、RepositoryPoint から Execution Workspace を materialize し、sandbox / mount / cache / cleanup / evidence を管理する実行基盤になる。 Runtime が Worker ごとに安全で安価な作業環境を用意できるようにする。Yoi の Runtime は、単に既存ディレクトリで Worker process を起動する launcher ではなく、RepositoryPoint から working directory を materialize し、sandbox / mount / cache / cleanup / evidence を管理する実行基盤になる。
この Objective の中心は、Worktree ライクな作業ディレクトリ管理、Repository cache、Execution Workspace allocation、sandboxed agent environment の境界を設計し、将来的に 1 つの Runtime が複数 Workspace / Repository の Worker を抱えられるようにすることである。 この Objective の中心は、Worker 用 working directory の materialization、Repository cache、working directory 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 の候補として扱う。 初期実装では 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 は、すべて working directory materialization strategy の候補として扱う。
## Motivation / background ## Motivation / background
@ -24,7 +24,7 @@ Runtime が Worker ごとに安全で安価な作業環境を用意できるよ
- Worker ごとに full clone すると容量と時間のコストが大きすぎる。 - Worker ごとに full clone すると容量と時間のコストが大きすぎる。
- `.yoi` / Backend fs-store / Workspace descriptor と、Worker 実行用 checkout / scratch / build output の lifecycle が混ざりやすい。 - `.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 を用意する責務を持つべきである。 Yoi は Workspace / Repository / Runtime を分ける方針になっている。Backend は Repository registry、RepositorySelector、RepositoryPoint、Ticket/Artifact evidence の authority を持つ。一方 Runtime は RepositoryPoint を受け取り、Worker が使う working directory を用意する責務を持つべきである。
したがって、Repository を持ってくる実体ディレクトリは Backend / Workspace store ではなく Runtime 管理領域に置く。`./.yoi` は local descriptor / compatibility / project record surface であり、Worker ごとの checkout、worktree、snapshot、sandbox root、build cache、dependency cache を置く場所ではない。 したがって、Repository を持ってくる実体ディレクトリは Backend / Workspace store ではなく Runtime 管理領域に置く。`./.yoi` は local descriptor / compatibility / project record surface であり、Worker ごとの checkout、worktree、snapshot、sandbox root、build cache、dependency cache を置く場所ではない。
@ -32,11 +32,11 @@ Yoi は Workspace / Repository / Runtime を分ける方針になっている。
## Glossary ## Glossary
- Runtime root: Runtime が自身の store、cache、Worker metadata、Execution Workspace allocation を管理する root。長期的には `~/.yoi/runtimes/<runtime-id>/` 配下など、Workspace backend store とは別に置く。 - Runtime root: Runtime が自身の store、cache、Worker metadata、working directory allocation を管理する root。長期的には `~/.yoi/runtimes/<runtime-id>/` 配下など、Workspace backend store とは別に置く。
- Repository cache: Runtime-local の共有 source/cache。Git なら bare mirror / object cache / packfile cache など。重く、長寿命で、複数 Worker allocation から共有される。 - Repository cache: Runtime-local の共有 source/cache。Git なら bare mirror / object cache / packfile cache など。重く、長寿命で、複数 Worker allocation から共有される。
- Execution Workspace: Worker ごとの作業環境。短寿命で、Worker が読み書きする root / mounts / scratch / overlay を含む。 - working directory: Worker ごとの作業環境。短寿命で、Worker が読み書きする root / mounts / scratch / overlay を含む。Browser-facing UI/API では `Workspace` と混同しないよう、この呼称に寄せる。`Volume` は storage backing の候補名であり、この作業領域そのものの呼称にはしない。
- Materialization strategy: RepositoryPoint から Execution Workspace を作る実装戦略。Git detached worktree、sparse checkout、CoW snapshot、reflink copy、overlay、container filesystem など。 - Materialization strategy: RepositoryPoint から working directory を作る実装戦略。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 を持つ。 - WorkingDirectoryAllocation: 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。 - 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 など。 - Dirty state policy: local uncommitted changes を Worker environment に含めるかどうかの方針。clean point only、patch artifact apply、snapshot current worktree など。
@ -64,7 +64,7 @@ Runtime root
- config bundles - config bundles
- worker metadata / transcript references - worker metadata / transcript references
- repository-cache - repository-cache
- execution-workspaces - working-directories
- sandbox state - sandbox state
- build/dependency cache - build/dependency cache
- cleanup ledger - cleanup ledger
@ -94,7 +94,7 @@ Runtime root
git/ git/
<repository-cache-key>/ <repository-cache-key>/
bare.git bare.git
execution-workspaces/ working-directories/
<allocation-id>/ <allocation-id>/
root/ root/
mounts/ mounts/
@ -106,14 +106,14 @@ Runtime root
### 2. clone ではなく materialize と呼ぶ ### 2. clone ではなく materialize と呼ぶ
Runtime は Repository を毎回 clone するのではない。Runtime は RepositoryPoint を Worker 用の Execution Workspace として materialize する。 Runtime は Repository を毎回 clone するのではない。Runtime は RepositoryPoint を Worker 用の working directory として materialize する。
```text ```text
RepositoryId + RepositorySelector RepositoryId + RepositorySelector
-> resolved RepositoryPoint -> resolved RepositoryPoint
-> Runtime repository-cache -> Runtime repository-cache
-> ExecutionWorkspaceMaterializer -> WorkingDirectoryMaterializer
-> ExecutionWorkspaceAllocation -> WorkingDirectoryAllocation
-> Worker process -> Worker process
``` ```
@ -128,15 +128,15 @@ Git の場合でも materialization strategy は複数あり得る。
- overlay filesystem - overlay filesystem
- external tool backed snapshot, e.g. Rift-like CoW workspace creation - external tool backed snapshot, e.g. Rift-like CoW workspace creation
### 3. Repository cache と Worker workspace を分離する ### 3. Repository cache と Worker working directory を分離する
full clone を Worker ごとに作らない。重い source/object data は Runtime-local repository cache に集約し、Worker ごとの Execution Workspace は cheap allocation にする。 full clone を Worker ごとに作らない。重い source/object data は Runtime-local repository cache に集約し、Worker ごとの working directory は cheap allocation にする。
Git v0 の方向: Git v0 の方向:
```text ```text
repository-cache/git/<repo-key>/bare.git repository-cache/git/<repo-key>/bare.git
execution-workspaces/<allocation-id>/root/<repository-id>/ working-directories/<allocation-id>/root/<repository-id>/
``` ```
初回: 初回:
@ -174,7 +174,7 @@ Dirty state を含める場合、Artifact/evidence には source RepositoryPoint
### 5. Sandbox を materialization と同じ境界で扱う ### 5. Sandbox を materialization と同じ境界で扱う
Execution Workspace は単なる directory path ではなく、Worker が見てよい filesystem view である。Runtime は Execution Workspace allocation と同時に sandbox/mount/authority を構築する。 working directory は単なる directory path ではなく、Worker が見てよい filesystem view である。Runtime は working directory allocation と同時に sandbox/mount/authority を構築する。
Worker に渡すもの: Worker に渡すもの:
@ -193,18 +193,18 @@ Worker が自分で発見してはいけないもの:
- `.yoi` authority-bearing internals - `.yoi` authority-bearing internals
- raw credentials - raw credentials
- Runtime socket/store/cache internals - Runtime socket/store/cache internals
- sibling Worker workspaces - sibling Worker working directories
Sandbox v0 は strong isolation でなくてもよい。ただし型と lifecycle は、後で container sandbox、namespace, mount filtering, network policy, secret boundary に拡張できる形にする。 Sandbox v0 は strong isolation でなくてもよい。ただし型と lifecycle は、後で container sandbox、namespace, mount filtering, network policy, secret boundary に拡張できる形にする。
### 6. Execution Workspace registry を持つ ### 6. working directory registry を持つ
Runtime は materialized workspace を filesystem だけでなく registry でも管理する。 Runtime は materialized workspace を filesystem だけでなく registry でも管理する。
必要な record: 必要な record:
```text ```text
ExecutionWorkspaceAllocation WorkingDirectoryAllocation
id id
runtime_id runtime_id
worker_id worker_id
@ -228,7 +228,7 @@ ExecutionWorkspaceAllocation
### 7. Heavy regenerable artifacts は policy で除外または cache 化する ### 7. Heavy regenerable artifacts は policy で除外または cache 化する
Worker workspace creation では、`node_modules`, `target`, `.venv`, framework cache, dist, build, coverage などを無条件に full copy しない。 Worker working directory creation では、`node_modules`, `target`, `.venv`, framework cache, dist, build, coverage などを無条件に full copy しない。
Materialization policy は以下を持てるようにする。 Materialization policy は以下を持てるようにする。
@ -245,26 +245,26 @@ Rift の filtered CoW creation のように、重い artifacts を除外しな
### Phase 1: Materialization boundary and legacy allocation record ### Phase 1: Materialization boundary and legacy allocation record
- `CreateWorkerRequest`Execution Workspace request / target placeholder を追加する。 - `CreateWorkerRequest`working directory request / target placeholder を追加する。
- `ExecutionWorkspaceMaterializer` trait を `worker-runtime` に追加する。 - `WorkingDirectoryMaterializer` trait を `worker-runtime` に追加する。
- `WorkerRuntimeExecutionBackend` が Worker spawn 前に materializer を呼ぶ順序にする。 - `WorkerRuntimeExecutionBackend` が Worker spawn 前に materializer を呼ぶ順序にする。
- v0 materializer は existing local root を explicit allocation として返してよいが、`direct_legacy_mount` として明示し、通常設計の final form と混同しない。 - v0 materializer は existing local root を explicit allocation として返してよいが、`direct_legacy_mount` として明示し、通常設計の final form と混同しない。
- Allocation record / cleanup policy / diagnostics の型を先に作る。 - Allocation record / cleanup policy / diagnostics の型を先に作る。
- Worker が source repository root を直接 scope として要求する経路を deprecated/legacy に閉じ込める。 - Worker が source repository root を直接 scope として要求する経路を deprecated/legacy に閉じ込める。
### Phase 2: Runtime root and execution workspace storage ### Phase 2: Runtime root and working directory storage
- `--runtime-root` を導入し、Runtime state / repository-cache / execution-workspaces / worker metadata / worker runtime dirs を Runtime root 配下へ寄せる。 - `--runtime-root` を導入し、Runtime state / repository-cache / working-directories / worker metadata / worker runtime dirs を Runtime root 配下へ寄せる。
- `--workspace` は legacy bootstrap input としてだけ扱い、Runtime identity / long-term workspace binding から外す。 - `--workspace` は legacy bootstrap input としてだけ扱い、Runtime identity / long-term workspace binding から外す。
- Runtime root default は user data 配下にする。 - Runtime root default は user data 配下にする。
- Execution Workspace allocation registry を Runtime root に保存する。 - working directory allocation registry を Runtime root に保存する。
### Phase 3: Git cached detached worktree materializer ### Phase 3: Git cached detached worktree materializer
- Git repository cache を Runtime root に作る。 - Git repository cache を Runtime root に作る。
- RepositorySelector を RepositoryPoint に解決する呼び出し境界を作る。 - RepositorySelector を RepositoryPoint に解決する呼び出し境界を作る。
- resolved commit/tree を evidence として残す。 - resolved commit/tree を evidence として残す。
- Worker ごとに detached worktree を `execution-workspaces/<allocation-id>/root/<repository-id>` に作る。 - Worker ごとに detached worktree を `working-directories/<allocation-id>/root/<repository-id>` に作る。
- Worker stop / cleanup 時に `git worktree remove` と registry cleanup を行う。 - Worker stop / cleanup 時に `git worktree remove` と registry cleanup を行う。
- dirty state は v0 では `clean_point_only` を default にし、dirty local workspace は明示 diagnostic で拒否する。 - dirty state は v0 では `clean_point_only` を default にし、dirty local workspace は明示 diagnostic で拒否する。
@ -284,13 +284,13 @@ Rift の filtered CoW creation のように、重い artifacts を除外しな
- container filesystem / mount namespace / network policy / secret handle / tool authority を Runtime allocation と統合する。 - container filesystem / mount namespace / network policy / secret handle / tool authority を Runtime allocation と統合する。
- Runtime が複数 Workspace / Repository の Worker を同時に抱える場合の namespace、quota、cleanup、audit boundary を固める。 - Runtime が複数 Workspace / Repository の Worker を同時に抱える場合の namespace、quota、cleanup、audit boundary を固める。
- remote/self-hosted/hosted Runtime fleet で repository cache と execution workspace storage をどう扱うかを設計する。 - remote/self-hosted/hosted Runtime fleet で repository cache と working directory storage をどう扱うかを設計する。
## Non-goals ## Non-goals
- v0 で完全な container sandbox を実装すること。 - v0 で完全な container sandbox を実装すること。
- Worker ごとに full clone すること。 - Worker ごとに full clone すること。
- `.yoi` や Backend workspace store に Worker execution workspace を置くこと。 - `.yoi` や Backend workspace store に Worker working directory を置くこと。
- Git worktree を唯一の materialization strategy として固定すること。 - Git worktree を唯一の materialization strategy として固定すること。
- Dirty local changes を暗黙に Worker に渡すこと。 - Dirty local changes を暗黙に Worker に渡すこと。
- Browser-facing API に raw host path、secret、Runtime internal store path を公開すること。 - Browser-facing API に raw host path、secret、Runtime internal store path を公開すること。
@ -298,10 +298,10 @@ Rift の filtered CoW creation のように、重い artifacts を除外しな
## Success criteria / exit conditions ## Success criteria / exit conditions
- Runtime root、Repository cache、Execution Workspace、Backend/Workspace store の境界が文書化されている。 - Runtime root、Repository cache、working directory、Backend/Workspace store の境界が文書化されている。
- Runtime が Worker spawn 前に Execution Workspace materializer を呼ぶ型と順序を持つ。 - Runtime が Worker spawn 前に working directory materializer を呼ぶ型と順序を持つ。
- Worker は source repository root ではなく materialized Execution Workspace を scope として起動する。 - Worker は source repository root ではなく materialized working directory を scope として起動する。
- Execution Workspace allocation が Runtime registry に記録され、cleanup policy を持つ。 - working directory allocation が Runtime registry に記録され、cleanup policy を持つ。
- Git/local repository の v0 materializer が full clone 連発ではなく shared cache / detached worktree / cheap allocation の方向に進んでいる。 - Git/local repository の v0 materializer が full clone 連発ではなく shared cache / detached worktree / cheap allocation の方向に進んでいる。
- dirty state policy が明示され、clean point、patch artifact、snapshot のどれを使ったか evidence に残せる。 - dirty state policy が明示され、clean point、patch artifact、snapshot のどれを使ったか evidence に残せる。
- Runtime process 起動時の `--workspace` は legacy bootstrap input として隔離され、Runtime identity や single workspace binding とみなされない。 - Runtime process 起動時の `--workspace` は legacy bootstrap input として隔離され、Runtime identity や single workspace binding とみなされない。
@ -315,10 +315,10 @@ Rift の filtered CoW creation のように、重い artifacts を除外しな
## Decision context ## Decision context
- Runtime は Worker 群を束ねる実行基盤であり、Worker 用の作業環境を用意する責務を持つ。 - Runtime は Worker 群を束ねる実行基盤であり、Worker 用の作業環境を用意する責務を持つ。
- Repository は clone されるものではなく、RepositoryPoint から Worker 用 Execution Workspace として materialize される。 - Repository は clone されるものではなく、RepositoryPoint から Worker 用 working directory として materialize される。
- Runtime execution storage は Backend/Workspace store と分離する。`.yoi` は Worker execution workspace 置き場ではない。 - Runtime execution storage は Backend/Workspace store と分離する。`.yoi` は Worker working directory 置き場ではない。
- full clone を Worker ごとに作らない。Runtime-local repository cache と Worker-local cheap workspace allocation を分ける。 - full clone を Worker ごとに作らない。Runtime-local repository cache と Worker-local cheap workspace allocation を分ける。
- Git detached worktree は v0 materialization strategy として有力だが、Git worktree 固定の設計にはしない。 - Git detached worktree は v0 materialization strategy として有力だが、Git worktree 固定の設計にはしない。
- CoW snapshot / reflink / btrfs snapshot / APFS clonefile / Rift-like workspace creation は、将来の materializer backend として検討する。 - CoW snapshot / reflink / btrfs snapshot / APFS clonefile / Rift-like workspace creation は、将来の materializer backend として検討する。
- Dirty local state は暗黙に渡さず、policy と evidence を持って扱う。 - Dirty local state は暗黙に渡さず、policy と evidence を持って扱う。
- Sandbox は後付けの別機能ではなく、Execution Workspace allocation と同じ境界で扱う。 - Sandbox は後付けの別機能ではなく、working directory allocation と同じ境界で扱う。