objective: clarify working directory terminology
This commit is contained in:
parent
9f1c17d4e9
commit
a6b93ceabc
|
|
@ -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 が両立している。
|
||||||
|
|
|
||||||
|
|
@ -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 と同じ境界で扱う。
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue
Block a user