yoi/.yoi/tickets/00001KVNKD56W/item.md

title	state	created_at	updated_at	assignee	queued_by	queued_at
Workspace DB canonical schema design	closed	2026-06-21T17:24:43Z	2026-06-22T09:27:06Z	null	workspace-panel	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 が通る。