# Hardware, Boot, And Storage Backlog

Detailed decompositions for hardware, boot packaging, block devices, and local
storage. `WORKPLAN.md` links here but should not inline these subtasks.

## Bootable Disk Image

- [ ] Add `make image` for GPT + EFI System Partition.
- [ ] Add `make run-disk` using OVMF.
- [ ] Add initial cloud upload/run notes after QEMU disk boot works.

## ACPI And PCIe Discovery

- [ ] Request and map Limine RSDP.
- [ ] Parse MADT enough to enumerate LAPIC/I/O APIC data.
- [ ] Parse MCFG and add PCIe ECAM config-space access beside legacy QEMU
      I/O-port access.

## Interrupt Infrastructure

Depends on ACPI and SMP Phase C LAPIC timer/IPI.

- [ ] Add I/O APIC driver: route IRQs to LAPIC vectors and handle source
      overrides.
- [ ] Add MSI/MSI-X setup: parse PCI capabilities and configure interrupt
      vectors.
- [ ] Add interrupt routing table: map PCI devices to vectors.
- [ ] Add optional x2APIC MSR backend for newer/high-core systems and firmware
      states where xAPIC is unavailable or undesirable.

## PCI/PCIe Infrastructure

Promotes PCI enumeration from a networking substep to a reusable subsystem
consumed by all device drivers.

- [ ] Add PCI config space access via legacy I/O ports and PCIe ECAM.
- [ ] Add bus enumeration for all buses/devices/functions.
- [ ] Add BAR parsing and MMIO mapping.
- [ ] Add capability list walking for MSI/MSI-X, virtio, and NVMe.

## Reusable Block-Device Path

- [ ] Factor shared virtio queue/transport helpers from virtio-net.
- [ ] Add virtio-blk sector read/write smoke.
- [ ] Define the first `BlockDevice` trait/capability boundary.

## Local Disk Storage Milestone

Visible outcome: default storage-focused QEMU boots from a disk image, exposes
a read-only directory from local disk, and proves one capnp object can be
persisted and read back after reboot.

Ordered gates:
- [ ] Add `Store`/`Namespace` plus file-I/O schema slices expected by the
      storage proposal.
- [ ] Add a RAM-backed `Store`/`Namespace` proof so naming and cap-return
      semantics are verified before disk work.
- [ ] Wire `virtio-blk` into the `BlockDevice` boundary and prove sector
      read/write in QEMU.
- [ ] Add a read-only filesystem service over `BlockDevice` with a focused
      QEMU directory-list/open/read proof.
- [ ] Add persistent `Store` backing over local disk and a reboot proof that
      stored capnp data survives.

## Writable Local Storage Milestone

Visible outcome: a storage-focused QEMU image can create, overwrite, truncate,
rename, and remove files through capability-scoped `Directory`/`File` caps,
persist both file and store mutations across reboot, and recover to a
consistent state after an unclean shutdown test.

Ordered gates:
- [ ] Decide and document one fail-closed concurrent-writer policy for the
      first writable filesystem slice.
- [ ] Add directory mutation operations and a focused QEMU proof for
      create/mkdir/remove/rename.
- [ ] Add writable `File` paths with overwrite, append, truncate, explicit
      `sync` behavior, and a focused QEMU proof.
- [ ] Persist writable filesystem metadata and data across reboot with
      verification that names, sizes, and contents survive.
- [ ] Add persistent `Store` mutation verification on the same local disk path
      so object writes/deletes survive reboot alongside filesystem data.
- [ ] Add one forced-poweroff or equivalent unclean-shutdown test and verify
      the filesystem and store recover without silent corruption.

## Managed Cloud Store Bridge

Visible outcome: application services can persist bounded Cap'n Proto records
through a cloud-backed capability while local QEMU tests exercise the same
semantics through a fake bridge.

Ordered gates:
- [ ] Define a provider-neutral `CloudStoreBridge` or app-specific `SaveStore`
      interface with put/get/compare-and-set/append operations, explicit size
      limits, profile or tenant scoping, schema version, and stale-write
      rejection.
- [ ] Add a local fake-cloud bridge used by host tests and QEMU smokes. It must
      reject wrong-profile loads, stale mutable writes, oversized records, and
      ledger rewrites.
- [ ] Add a GCP deployment note for Cloud Run bridge service, Firestore Native
      mode mutable indexes/profile summaries, Cloud Storage versioned blobs, and
      Secret Manager credentials.
- [ ] Add Cloud KMS keying notes for managed game-world storage: key ring/key per
      world or shard, narrow encrypt/decrypt IAM authority, rotation, retired
      world revocation, and audit logging.
- [ ] Keep provider credentials outside ordinary capOS clients. Only the bridge
      service receives cloud credentials; game/storage clients receive narrow
      capabilities.
- [ ] Add lifecycle/retention/cost controls before writing real snapshots or
      evidence blobs to Cloud Storage.
- [ ] Treat local disk-backed `Store` as the offline/QEMU baseline even when
      cloud persistence is available.

## User-Owned Browser Save Transport

Visible outcome: private user data can be backed up through the user's browser
to Google Drive or Firebase as encrypted capsules while capOS never receives
provider tokens.

Completed policy and host-test gates:
- [x] Define provider-neutral browser transport policy for opaque encrypted save
      capsules, opaque provider handles, capsule metadata, and wrapped-DEK
      metadata without plaintext, token, key-capability, or KMS grant authority.
- [x] Add fake Drive and fake Firebase adapters for host tests. They model user
      deletion, duplicate writes, stale versions, rollback attempts, missing
      network, non-opaque handles, authenticated-user mismatch, and Firebase
      auth UID path-segment injection.
- [x] Add Google Drive `appDataFolder` notes using the narrow `drive.appdata`
      scope for app-private user backup files.
- [x] Add Firebase/Firestore notes for per-user encrypted capsule documents and
      offline cache/sync behavior, with the limitation that encrypted game
      semantics cannot be validated by backend rules.
- [x] Document that GCP-backed world capsules are encrypted with game-world
      Cloud KMS envelope encryption, while local-only capsules use local
      capOS-host key material.
- [x] Record that browser OAuth/Firebase tokens stay in the browser companion
      or web terminal host and must not enter ordinary capOS clients, game
      services, or QEMU transcripts.
- [x] Record that game-world key capabilities and KMS decrypt/unwrap grants are
      not exposed to the browser; the browser may transport ciphertext,
      provider handles, capsule metadata, and wrapped-DEK handles only.

Future real-provider integration gates:
- [ ] Implement real Google Drive and Firebase browser-companion adapters after
      the provider-token boundary is exercised outside ordinary capOS clients.
- [ ] Reuse the existing save-capsule restore rejection tests as the acceptance
      gate for real provider adapters: tampered, wrong-profile, stale,
      oversized, unknown-content, and unsigned capsules must still fail before
      provider bytes can mutate save state.
- [ ] Add real-provider failure-mode coverage for deletion, duplicate writes,
      stale versions, rollback attempts, offline cache/sync replay, and missing
      network using the same semantics as the fake adapters.

## Boot Binary ISO Layout

Move ELF payloads out of the Cap'n Proto manifest blob and into the ISO 9660
filesystem as plain files, read on demand through a minimal kernel ISO driver.
On-demand ISO reads eliminate the manifest size limit, keep the manifest as
pure topology, and decouple binary file changes from manifest rebuilds.

Ordered gates:
- [ ] Minimal ATA PIO CD-ROM read path: identify the ATAPI device on the
      primary or secondary IDE bus, implement `READ(12)` packet commands in
      PIO mode, and surface a bounded `read_sectors(lba, count, buf)`
      interface used only during binary loading.
- [ ] Read-only ISO 9660 driver: parse the primary volume descriptor, walk the
      directory tree to `/boot/bins/`, implement `open_file(name) -> (lba,
      size)`, and validate sector reads are in-bounds before use.
- [ ] `mkmanifest` copies ELF files to `iso_root/boot/bins/` and leaves
      `NamedBlob.data` empty; the manifest carries names only.
- [ ] Kernel `run_init()` opens the ISO driver, validates all manifest binary
      names are present under `/boot/bins/`, and stores `(name, lba, size)`
      entries as the `BootBinary` registry. `ProcessSpawnerCap` reads ELF
      sectors on demand; `BootPackage.readBinaryChunk` serves bytes from the
      ISO driver. Retire `NamedBlob.data` from all kernel paths.
- [ ] Update `BOOT_MANIFEST_MAX_BYTES` docs and add per-binary Makefile copy
      targets so only changed files are re-copied on incremental `make`.

## Cloud Device Tracks

- [ ] Add NVMe controller init: admin queue pair and identify
      controller/namespace.
- [ ] Add NVMe I/O queue pair: submission/completion rings and doorbell
      writes.
- [ ] Add NVMe read/write commands with PRP-based DMA transfers.
- [ ] Implement `BlockDevice` for NVMe.
- [ ] Add QEMU NVMe testing via `-device nvme`.
- [ ] GCP NIC path: virtio-net first, then gVNIC.
- [ ] AWS NIC path: ENA driver.
- [ ] Azure NIC path: MANA driver.