yoi/.yoi/tickets/00001KV5R5V2S/item.md

title	state	created_at	updated_at	assignee	readiness	risk_flags	queued_by	queued_at
Plugin: package discovery and explicit enablement resolver	queued	2026-06-15T13:40:15Z	2026-06-15T13:59:47Z	null	implementation_ready	plugin package-loading discovery enablement capability-boundary startup-restore	workspace-panel	2026-06-15T13:59:47Z

Background

Plugin を利用可能にする最初の実装として、Plugin package を安全に発見・検査し、明示設定に基づいて enablement target として resolve できるようにする。

この Ticket では Plugin code の実行、Tool / Hook / Service / Ingress の登録、WASM runtime、https / fs host API 実装は行わない。package discovery と explicit enablement resolver を先に固め、後続の Plugin runtime / surface 実装が同じ解決結果を使えるようにする。

既存設計では以下を分離する。

package discovery != enablement != runtime initialization != contribution registration

package が存在するだけで実行・登録されてはならない。Yoi は package を read-only に発見し、profile / config 側の明示 enablement entry と照合できるところまでをこの Ticket の範囲とする。

Scope

• Plugin package discovery
• Plugin package archive / directory safety validation
• plugin.toml manifest parsing
• Plugin package identity resolution
• Explicit enablement entry resolution
• Resolved Plugin metadata / diagnostics surface
• Startup / snapshot restore で再現可能な resolved input の保持または再構築方針

Package locations

最初の discovery source は以下を対象にする。

• User plugin store:
  • ${XDG_DATA_HOME:-~/.local/share}/yoi/plugins/*.yoi-plugin
• Workspace plugin store:
  • <workspace>/.yoi/plugins/*.yoi-plugin

実装上、.yoi-plugin を archive として扱うか directory として扱うかは、既存設計 00001KT0Z4BK8 を確認して合わせる。未実装部分がある場合は、最小実装を明示し、後続 Ticket で拡張できる構造にする。

Requirements

• Plugin package discovery は read-only とする。
  • 発見した package を実行しない。
  • Tool / Hook / Service / Ingress を登録しない。
  • package の存在だけで Plugin が有効化されない。
• plugin.toml を package root から読み込む。
  • 必須 metadata を parse する。
  • unsupported / incompatible api version は fail closed にする。
• Package safety checks を行う。
  • path traversal を reject する。
  • package root 外への symlink / escape を reject する。
  • bounded file count / total size / manifest size を設ける。
  • deterministic digest を計算する。
  • malformed package は diagnostic に残すが、Pod startup 全体を不要に壊さない。
• Plugin identity を source-qualified に扱う。
  • user:<id>
  • project:<id>
  • builtin:<id>
• Unqualified id が複数 source に一致する場合は ambiguous として fail closed にする。
• Profile / config 側の explicit enablement entry を読む。
  • exact config location / shape は既存 Profile / plugin design に合わせ、必要なら最小の typed structure を追加する。
  • enablement entry は package ref、version / version constraint、digest pin、enabled surfaces、grant request / grant reference を表現できるようにする。
• Enablement resolver は discovered package と enablement entry を照合する。
  • missing package
  • duplicate package id
  • ambiguous ref
  • version mismatch
  • digest mismatch
  • incompatible api version
  • requested surface unsupported
  • grant missing / unsupported を diagnostic として区別できるようにする。
• Resolved Plugin は後続の runtime initialization / contribution registration に渡せる typed data として表す。
  • package identity
  • source
  • package path
  • digest
  • manifest metadata
  • enabled surfaces
  • effective grants / unresolved grants
  • diagnostics
• Startup / snapshot restore で同じ resolved Plugin set を再現できること。
  • runtime-only mutable state に依存しない。
  • 必要な場合は Pod metadata / snapshot に resolved digest 等を含めるか、startup 時に deterministic に再解決する。
• Diagnostics は model-visible context に勝手に差し込まない。
  • user-visible / logs / snapshot など既存の診断面に合わせる。
  • secret-like path / auth / file content を出さない。

Non-goals

• Plugin code execution。
• WASM runtime 実装。
• Tool / Hook / Service / Ingress の実登録。
• https host API 実装。
• fs host API 実装。
• external network / filesystem side effect の実行。
• plugin package manager / install / update / registry 実装。
• package signature / trust chain 実装。
• MCP bridge との統合。

Acceptance criteria

• User / workspace plugin store から .yoi-plugin package を発見できる。
• Valid package の plugin.toml を parse し、typed manifest と deterministic digest を得られる。
• Invalid package は fail closed し、bounded diagnostic として報告される。
• Package が存在するだけでは Tool / Hook / Service / Ingress は登録されない。
• Profile / config の explicit enablement entry なしでは Plugin は有効化されない。
• Enablement entry と discovered package を照合し、resolved Plugin metadata を生成できる。
• user:<id> / project:<id> / builtin:<id> の source-qualified identity を扱える。
• ambiguous unqualified id は fail closed する。
• version mismatch / digest mismatch / incompatible api version / missing package が区別可能な diagnostic になる。
• Startup / restore 時に resolved Plugin set が deterministic に再現できる。
• Tests cover:
  • valid user package discovery
  • valid workspace package discovery
  • package without enablement is not active
  • explicit enablement resolves package
  • duplicate / ambiguous id fail closed
  • digest mismatch fail closed
  • path traversal / root escape rejected
  • unsupported api version rejected
  • malformed manifest diagnostic
  • no contribution registration from discovery-only path
• Validation: focused tests for plugin discovery/resolver, cargo fmt --check, relevant cargo check / cargo test, git diff --check, and nix build .#yoi if runtime resources / packaging / dependency graph change.

Implementation notes

• Prefer adding a small typed Plugin package/resolver module rather than embedding resolver logic inside runtime launch code.
• Keep terminology aligned with the design record:
  • Plugin runtime
  • Plugin surface
  • Plugin host API
• Do not reintroduce contribution category as user-facing terminology.
• Host APIs remain intentionally narrow. If this Ticket needs to mention APIs, use https and fs, not web.
• Discovery and enablement should integrate with the existing Profile / feature contribution direction without giving plugins ambient workspace filesystem authority.

Related work

• 00001KSXRQ4G8 — Plugin runtime / surface / minimal host API model design.
• 00001KT0Z4BK8 — Plugin package / discovery format design.
• 00001KTR81P9X — pod::feature API / plugin host substrate follow-up.