# hiperiso Interface Contracts
# =============================
# ALL components MUST conform to these definitions.
# This file is the single source of truth for inter-component interfaces.

# ── Kernel Command Line Parameters (GRUB2 → host kernel → initramfs) ──────────
# These are set by the GRUB2 hiperiso_boot command and parsed by initramfs/init.
HIPERISO_ISO_PATH=""        # Path to ISO file on USB data partition (e.g. /ISOs/ubuntu.iso)
HIPERISO_LOG_DIR=""         # Directory for boot logs (e.g. /hiperiso/logs/ubuntu/)
HIPERISO_TRACE_LEVEL=""     # Trace tier: "standard" | "detailed" | "full" | "none"
HIPERISO_GUEST_RAM=""       # Guest RAM in MB (default: 2048)
HIPERISO_GUEST_CPUS=""      # Guest vCPUs (default: 2)
HIPERISO_DISPLAY=""         # Display mode: "none" | "gtk" | "vnc" (default: none)
HIPERISO_VGA=""             # VGA mode: "none" | "std" | "virtio" (default: std)
HIPERISO_FALLBACK=""        # Force fallback mode: "1" skips KVM check

# ── Plugin Parameters ─────────────────────────────────────────────────────────
# These are resolved by the GRUB2 module from hiperiso.json plugins and passed
# via kernel cmdline to the initramfs, which translates them to QEMU args.
HIPERISO_AUTO_INSTALL=""    # Path to auto-install script (kickstart/preseed)
HIPERISO_PERSISTENCE=""     # Path to persistence .dat file
HIPERISO_DUD=""             # Path to Driver Update Disk image
HIPERISO_INJECTION=""       # Path to injection archive (tar.gz)
HIPERISO_CONF_REPLACE=""    # Config replacement: "org=/path;new=/path"
HIPERISO_SECURE_BOOT=""     # "1" = use Secure Boot OVMF firmware
HIPERISO_TPM=""             # "1" = attach virtual TPM (swtpm)
HIPERISO_CPU_FEATURES=""    # Comma-separated CPU features: "vmx,svm"
HIPERISO_BOOT_MODE=""       # "normal" | "memdisk" | "grub2"
HIPERISO_NET_DUMP=""        # "1" = add virtio-net + pcap capture to network.pcap

# ── USB Partition Layout ─────────────────────────────────────────────────────
DATA_PART="/dev/sdX1"       # Partition 1: Data partition (exFAT/NTFS, rest of disk)
EFI_PART="/dev/sdX2"        # Partition 2: EFI System Partition (FAT16, 64MB)
EFI_MOUNT="/mnt/efi"         # Mount point for ESP during install
DATA_MOUNT="/mnt/usb"        # Mount point for data partition at runtime

# ── File Paths (on EFI partition) ────────────────────────────────────────────
EFI_PAYLOAD_DIR="/EFI/hiperiso"
KERNEL_PATH="${EFI_PAYLOAD_DIR}/vmlinuz"
INITRAMFS_PATH="${EFI_PAYLOAD_DIR}/initramfs.cpio.gz"
OVMF_PATH="${EFI_PAYLOAD_DIR}/OVMF.fd"
TRACE_EVENTS_DIR="${EFI_PAYLOAD_DIR}/trace"
GRUB_CFG="/EFI/BOOT/grub.cfg"
HIPERISO_JSON="${DATA_MOUNT}/hiperiso/hiperiso.json"

# ── Log Directory Structure (per ISO boot session) ───────────────────────────
# Each boot creates a unique timestamped directory:
#   /hiperiso/logs/<sanitized-iso-basename>_<UTC-timestamp>/
#
# Guaranteed artifacts (always written once the session dir exists, even when
# the boot fails before QEMU launches):
#   session.json     - Session manifest (structured metadata for agent intake)
#   status.json      - Live status, rewritten at every stage transition
#   env.txt          - Environment snapshot (host kernel, RAM, CPU, KVM, config)
#
# Conditional artifacts (present depending on how far the boot progressed):
#   serial.log       - Tier 1: Serial console output (written by QEMU)
#   trace.bin        - Tier 2+: QEMU simpletrace (only when trace_level != none)
#   qemu.cmdline     - Exact QEMU command line used (written before launch)
#   monitor.sock     - QEMU monitor socket (live introspection while guest runs)
#   timing.dat       - Raw boot phase timing (TSV: phase<TAB>uptime<TAB>iso8601)
#   timing.json      - Structured boot timing with per-phase deltas
#   hw/              - Hardware inventory directory (host + QEMU guest data)
#   network.pcap     - Network packet capture (only when net_dump=1)
#   report.json      - Generated analysis report (auto-run after QEMU exits)
#   report.txt       - Human-readable report (auto-run after QEMU exits)
#   report.log       - Raw output from the hiperiso-log analyze invocation
#   analysis.meta    - Flat KEY=VALUE derived-analysis sidecar (written by
#                      hiperiso-log; consumed by init to fold boot_result /
#                      failure_domain / graphics hints into the final manifest)
#   HEARTBEAT        - Periodic liveness marker from the log_flush daemon
#   SESSION_COMPLETE - Sentinel written when the session ended (success OR
#                      failure), by hiperiso_finalize_session
#   FAILURE.txt      - Human-readable failure summary (present only on failure)
#
# ── session.json (session manifest; written at start, REWRITTEN at end) ──────
# On start only the fields up to start_time_utc/kvm/trace_level/ram/cpus are
# present with status="started".  At session end hiperiso_finalize_session()
# rewrites it as the canonical manifest with the full field set below.
# {
#   "session_id":      "<basename>_<UTC-timestamp>",   # == dir basename
#   "status":          "complete" | "failed",          # final lifecycle state
#   "result":          "success" | "failure" | "incomplete" | "no_serial",
#                                                              # derived boot result
#   "iso_path":        "/ISOs/<name>.iso",
#   "iso_basename":    "<name>.iso",
#   "log_dir":         "/hiperiso/logs/<dir>",          # no trailing /
#   "start_time_utc":  "YYYY-MM-DDTHH:MM:SSZ",          # captured at start
#   "end_time_utc":    "YYYY-MM-DDTHH:MM:SSZ",          # captured at finalize
#   "kvm":             "available" | "unavailable" | "unknown",
#   "trace_level":     "standard" | "detailed" | "full" | "none",
#   "guest_ram_mb":    2048,                            # number, MB
#   "guest_cpus":      2,                               # number
#   "qemu_exit_code":  0,                               # number or null
#   "report_available": 1,                              # 1 if report.json exists
#   "host": {                                            # non-identifying host metadata
#     "kernel_version": "Linux version 6.6.0...",
#     "cpu_model":       "Intel(R) Core(TM) i7-...",
#     "cpu_logical_cores": 8,
#     "total_ram_mb":    16384,
#     "virt_supported":  true
#   },
#   "analysis": {                                       # derived by hiperiso-log
#     "boot_result":        "success" | "failure" | "incomplete" | "no_serial",
#     "boot_stage_final":   "login" | "userspace" | ... | "error" | "unknown",
#     "failure_domain":     "none" | "firmware" | "bootloader" | "kernel" |
#                           "hardware" | "userspace" | "unknown",
#     "reached_login":      1,
#     "kernel_panic_count": 0,
#     "error_count":        0,
#     "has_serial":         1,
#     "has_trace":          1,
#     "boot_duration_ms":   12345,
#     "graphics_drivers":   "i915,virtio_gpu",           # comma-sep, may be ""
#     "graphics_resolution": "1024x768"                 # may be ""
#   },
#   "hw_inventory": {                                    # hardware data availability
#     "available":       true,                           # false if hw/ is empty
#     "files":           "host_cpuinfo.txt,qemu_qtree.txt,...",
#     "has_timing":      true                            # timing.json was generated
#     "has_network_pcap":false                           # network.pcap exists
#   }
# }
#
# ── /hiperiso/logs/index.jsonl (append-only global corpus index) ─────────────
# One compact JSON object per line; appended on BOTH success and failure by
# hiperiso_finalize_session().  Machine-readable for corpus ingestion:
#   {"session_id":"...","status":"complete","result":"success",
#    "iso_basename":"...","iso_path":"...","log_dir":"...",
#    "start_time_utc":"...","end_time_utc":"...",
#    "kvm":"available","trace_level":"standard",
#    "qemu_exit_code":0,"report_available":1,
#    "boot_result":"success","boot_stage_final":"login","failure_domain":"none",
#    "graphics_drivers":"i915"}
#
# ── status.json (live status, rewritten at each stage transition) ────────────
# {
#   "session_id":     "<basename>_<UTC-timestamp>",   # string
#   "status":         "started" | "running" | "complete" | "failed",
#   "stage":          "<current_stage>",              # see stages below
#   "qemu_exit_code": 0,                              # number, optional
#   "timestamp_utc":  "YYYY-MM-DDTHH:MM:SSZ"
# }
# Known stages: mounted | kvm_ok | tcg_emulation | launching_qemu |
#               qemu_exited | session_complete | fallback_no_kvm |
#               iso_not_found | fatal_error

# ── Trace Event Tiers ───────────────────────────────────────────────────────
# Tier 1 (standard): serial + basic disk I/O (always on)
# Tier 2 (detailed): + PCI config space + port I/O
# Tier 3 (full):     + MMIO memory_region_ops (very slow, debug only)

# ── Config File Format (hiperiso.json) ──────────────────────────────────────
# JSON format:
# {
#   "control": { ... },
#   "theme": { ... },
#   "menu_alias": [ ... ],
#   "menu_tip": [ ... ],
#   "iso_overrides": {
#     "*./windows11*.iso": { "ram": 4096, "tpm": true, "cpu_features": ["vmx"] }
#   }
# }

# ── hiperiso-log Tool Interface ─────────────────────────────────────────────
# Usage: hiperiso-log analyze <log_dir>
# Usage: hiperiso-log trace <trace.bin> [--format json|csv|text]
# Usage: hiperiso-log serial <serial.log> [--stages]
# Output: writes report.json, report.txt, and analysis.meta into <log_dir>

# ── Build Architecture ─────────────────────────────────────────────────────
# The GRUB binary shipped as $EFI_PAYLOAD_DIR/../BOOTX64.EFI is built from
# Ventoy 2.04 + vendor/grub2-modsrc.tar.xz (Ventoy's GRUB core patches).
# This is the "substrate" approach: rather than rename Ventoy symbols to
# hiperiso_*, we keep the Ventoy module intact and bridge to a hiperiso
# runtime via two channels:
#
#   1. Runtime cmdline:  the GRUB script function `hiperiso_boot` in
#      $GRUB_CFG constructs a `hiperiso_iso=...` cmdline and runs
#      `linux` + `initrd` + `boot` against the host kernel + QEMU
#      initramfs under $EFI_PAYLOAD_DIR/.
#
#   2. Layout:  the FAT16 volume label MUST be "VTOYEFI" and the
#      /ventoy/ventoy.cpio file MUST exist at the ESP root — both are
#      hardcoded checks in the modsrc's ventoy_check_official_device().
#      The label and file are produced by scripts/package_release.sh.
#
# Modsrc patches: scripts/build_grub2_204.sh applies a single sed
# pass to the unpacked modsrc tree to (1) accept a 64MB ESP (modsrc
# hardcodes 32MB / 65536 sectors) and (2) tolerate the missing 0x22
# GPT-MBR marker byte. (The 0x22 marker is written by the installer
# in HiperisoWorker.sh — not by the build.) Anything beyond these
# patches is upstream Ventoy territory; do not modify modsrc without
# bumping the version check in scripts/build_all.sh.
#
# The hiperiso-specific C sources in src/grub2/hiperiso_*.c are kept
# in-tree as historical reference but are not compiled or shipped.
# They document an earlier (incomplete) rebrand attempt; their
# unmodified use would break moddep.lst generation.

