--- title: 'Workspace DB canonical schema design' state: 'closed' created_at: '2026-06-21T17:24:43Z' updated_at: '2026-06-22T09:27:06Z' assignee: null queued_by: 'workspace-panel' queued_at: '2026-06-22T08:48:39Z' --- ## 背景 Workspace web control plane は、Rust backend / SQLite store / static SPA / read-only filesystem bridge まで立ち上がっている。ただし現在の SQLite schema は起動・API skeleton 用の足場であり、Ticket / Objective / Repository / Host / Worker / Artifact を将来 DB 正本にするための canonical schema はまだ固まっていない。 DB 設計は過度に難しく扱わず、まずは既存 filesystem Ticket/Objective model と現在の orchestration 運用を素直に relational/event model へ写す。重要なのは、`.yoi` filesystem record をすぐ捨てることではなく、Web/API/Orchestrator が将来 DB authority に移れるだけの record 境界を決めること。 長期方針: - Ticket / Objective は Workspace 配下に平たく存在する。 - Repository は Workspace に接続される source/storage であり、Git Repository はその一種。 - Ticket は必要に応じて Repository target selector を持つ。 - Ticket thread/events が実行履歴の authority であり、Ticket state は current snapshot として持つ。 - Worker は Ticket に関連づく logical agent/session だが、v0 では DB 正本として永続化しない。Host/Worker 一覧は runtime inspection / future Host protocol から逐次取得する live view とする。 - Worker の一元管理、データ永続化、アーカイブは将来必要になるが、Host/Worker protocol と lifecycle requirements が固まるまで v0 schema には入れない。 - Host は Worker が観測される実行環境または capacity を表すが、v0 では canonical table ではなく live view とする。 - CI/check information should be represented as Ticket events plus Artifact links in v0. If richer CI status is needed, design it later as a separate actions-like subsystem rather than a generic validation table. - Orchestrator は将来的に fs/Bash/Git を直接持たず、Ticket / TicketEvent / TicketWorkerLink / live Host/Worker view / Artifact / Review の DB/API surface だけを見る。 - Memory / Knowledge の本格再設計はこの Ticket では扱わず、保存先を Workspace backend へ移す時に回収する。 ## 要件 ### Canonical records / tables DB design は `artifacts/schema-v0.md` を主たる設計記録とする。Ticket 本文では scope と要求だけを示す。 `schema-v0.md` では以下を明確に定義する。 - record / event / reference の区別。 - ID / timestamp / no-catch-all-payload column conventions。 - `AuthorRef` v0。 - event author/source を記録する typed snapshot。 - 初期実装では full `actors` table を必須にしない。 - auth / permission / assignment / team membership が必要になった時点で `actors` table へ昇格できる。 - table candidates and required columns: - `workspaces` - `tickets` - `ticket_events` - `ticket_relations` - `objectives` - `objective_ticket_links` - `repositories` - `ticket_targets` - `ticket_target_paths` - `ticket_worker_links` - `artifacts` - `audit_events` - Orchestrator no-fs/no-bash の read/write surfaces。 - filesystem read-through から DB authority への migration modes。 初期設計で曖昧な `actors` entity を置かない。必要なのは event authorship であり、v0 では `AuthorRef` fields として扱う。 ### Authority / migration stance - 当面は `.yoi/tickets` / `.yoi/objectives` filesystem read-through を維持する。 - DB schema は canonical target として設計するが、この Ticket だけで full migration はしない。 - import/projection/export の方針を決める。 - filesystem -> DB import。 - DB -> filesystem export / compatibility snapshot。 - read-through bridge と DB authority の切り替え条件。 - 二重正本を避けるため、write path をいつ DB に切り替えるかを明記する。 - SQLite first でよいが、将来 Postgres/multi-tenant へ進めるよう、`workspace_id` を全主要 record に含める。 ### Orchestrator no-fs/no-bash surface DB/API だけを見て Orchestrator が判断できるように、以下の read/write surface を設計する。 Orchestrator が読むもの: - Ticket state/thread/relations/targets。 - Ticket-associated WorkerRef links and worker status events。 - Objective context。 - Live Host/Worker view from runtime inspection or future Host protocol。 - Repository target and artifact source revision fields。 - Artifact summaries/diff metadata/log summaries。 - Review evidence。 Orchestrator が作るもの: - Ticket comment/decision/state transition request。 - Ticket execution request / WorkerRef assignment / worker status events。 - Worker job request / assignment request。 - Review/check request。 - Close/done decision with evidence references。 fs/Bash/Git 操作は Host/Worker に閉じ込める。Orchestrator は raw repository filesystem や shell access を authority として持たない。 ### Initial implementation slice この Ticket は design-only でもよいが、可能なら最小 schema migration まで含める。 - `crates/workspace-server` の SQLite schema を canonical design に合わせて整理する。 - 既存 placeholder `runs` / `runners` naming を、structured ticket events / live Host/Worker API / `ticket_worker_links` へ寄せる。 - Migration versioning の方針を明記する。 - Existing read API を壊さない。 ## Non-goals - Full DB migration of existing `.yoi/tickets` / `.yoi/objectives`。 - Web UI からの Ticket/Objective mutation 実装。 - Memory / Knowledge の本格再設計。 - Multi-tenant production SaaS schema の完全設計。 - Auth/billing/quota/security の完全実装。 - Git hosting service の実装。 - Orchestrator profile から fs/Bash を実際に剥がすこと。 ## 受け入れ条件 - Workspace DB canonical schema design が `artifacts/schema-v0.md` または同等の design record として記録されている。 - `schema-v0.md` が record / event / reference の区別を定義している。 - Table/record 境界として Workspace / Ticket / TicketEvent / TicketRelation / Objective / ObjectiveTicketLink / Repository / TicketTarget / TicketTargetPath / TicketWorkerLink / Artifact / AuditEvent が定義されている。 - Separate top-level Run entity/table を v0 では作らず、structured Ticket events と TicketWorkerLink relation を execution history/management surface とする方針が明記されている。 - Host/Worker は v0 DB canonical table ではなく live runtime view とし、Ticket には WorkerRef snapshot/link を保存する方針が明記されている。 - Event/request/audit authorship は `AuthorRef` v0 として required fields まで定義されている。 - 初期実装で full Actor entity/table を必須にしない方針と、将来 actors table へ昇格できる条件が明記されている。 - CI/check status は v0 core schema では Ticket events + Artifact links として扱い、actions-like subsystem は future work とする方針が明記されている。 - `.yoi` filesystem read-through から DB authority へ移る migration/export/import 方針が明記されている。 - Orchestrator no-fs/no-bash を可能にする DB/API read/write surface が明記されている。 - Memory / Knowledge は deferred として扱われ、この schema design の必須 scope から外れている。 - SQLite first だが、全主要 record に `workspace_id` を持たせる方針が明記されている。 - 既存 `runner` placeholder naming を Host/Worker に移す方針が明記されている。 - 実装まで含める場合は `cargo fmt --check`、`cargo test -p yoi-workspace-server`、`cargo check`、`git diff --check`、`yoi ticket doctor`、`nix build .#yoi --no-link` が通る。