id: T014
name: PlasmaVMC FireCracker backend
status: complete
goal: Implement FireCracker HypervisorBackend for lightweight microVM support
priority: P1
owner: peerA (strategy) + peerB (implementation)
created: 2025-12-08
depends_on: [T013]

context: |
  PROJECT.md item 4 specifies PlasmaVMC should support multiple VM backends:
  "KVM, FireCracker, mvisorなどなど"

  T011 implemented KvmBackend with QMP lifecycle.
  T012-T013 added tenancy and ChainFire persistence.

  FireCracker offers:
  - Faster boot times (< 125ms)
  - Lower memory overhead
  - Security-focused (minimal device model)
  - Ideal for serverless/function workloads

  This validates the HypervisorBackend trait abstraction from T005 spec.

acceptance:
  - FireCrackerBackend implements HypervisorBackend trait
  - Can create/start/stop/delete FireCracker microVMs via trait interface
  - Uses FireCracker API socket (not QMP)
  - Integration test (env-gated) proves lifecycle works
  - VmService can select backend via config (kvm vs firecracker)

steps:
  - step: S1
    action: FireCracker integration research + design
    priority: P0
    status: complete
    owner: peerB
    completed: 2025-12-08
    notes: |
      Research FireCracker API (REST over Unix socket).
      Design FireCrackerBackend struct and config.
      Identify dependencies (firecracker binary, jailer).
    deliverables:
      - brief design note in task directory
      - config schema for firecracker backend
    evidence:
      - design.md: FireCracker API調査、構造体設計、制限事項、実装アプローチ
      - config-schema.md: 環境変数ベースの設定スキーマ、検証ルール

  - step: S2
    action: Implement FireCrackerBackend trait
    priority: P0
    status: complete
    owner: peerB
    completed: 2025-12-08
    notes: |
      Implement HypervisorBackend for FireCracker.
      Handle socket communication, VM lifecycle.
      Map VmConfig to FireCracker machine config.
    deliverables:
      - FireCrackerBackend in plasmavmc-firecracker crate
      - Unit tests for backend capabilities and spec validation
    evidence:
      - plasmavmc/crates/plasmavmc-firecracker/: FireCrackerBackend実装完了
      - FireCrackerClient: REST API over Unix socket実装
      - 環境変数による設定実装完了

  - step: S3
    action: Backend selection in VmService
    priority: P1
    status: complete
    owner: peerB
    completed: 2025-12-08
    notes: |
      Add config/env to select hypervisor backend.
      VmService instantiates correct backend based on config.
      Default remains KVM for backwards compatibility.
    deliverables:
      - PLASMAVMC_HYPERVISOR env var (kvm|firecracker)
      - VmService backend factory
    evidence:
      - plasmavmc/crates/plasmavmc-server/src/main.rs: FireCrackerバックエンド登録
      - plasmavmc/crates/plasmavmc-server/src/vm_service.rs: PLASMAVMC_HYPERVISOR環境変数サポート

  - step: S4
    action: Env-gated integration test
    priority: P1
    status: complete
    owner: peerB
    completed: 2025-12-08
    notes: |
      Integration test for FireCracker lifecycle.
      Requires firecracker binary and kernel image.
      Gated by PLASMAVMC_FIRECRACKER_TEST=1.
    deliverables:
      - passing integration test
      - evidence log
    evidence:
      - plasmavmc/crates/plasmavmc-firecracker/tests/integration.rs: 環境ゲート付き統合テスト実装完了
      - integration-test-evidence.md: テスト実装詳細と実行手順、証拠ログ
      - "テスト実行確認: cargo test --package plasmavmc-firecracker --test integration -- --ignored で正常にスキップされることを確認"

blockers: []

evidence:
  - design.md: S1完了 - FireCracker統合設計ドキュメント
  - config-schema.md: S1完了 - 設定スキーマ定義
  - plasmavmc/crates/plasmavmc-firecracker/: S2完了 - FireCrackerBackend実装
  - plasmavmc/crates/plasmavmc-server/: S3完了 - バックエンド選択機能

notes: |
  FireCracker resources:
  - https://github.com/firecracker-microvm/firecracker
  - API: REST over Unix socket at /tmp/firecracker.socket
  - Needs: kernel image, rootfs, firecracker binary

  Risk: FireCracker requires specific kernel/rootfs setup.
  Mitigation: Document prerequisites, env-gate tests.