/*
  StarForth — Steady-State Virtual Machine Runtime

  Copyright (c) 2023–2025 Robert A. James
  All rights reserved.

  Licensed under the StarForth License, Version 1.0
*/

/**
 * capsule_runcap.h - RUNCAP: runtime capsule construction from thumbdrive
 * content (FABRIC-3.md §F.6/§F.18).
 *
 * A user's identity source (raw FORTH init/personality text, minted by
 * MINT into a home-blocks drive's identity_src region) never exists at
 * build time, so it can never appear in the compile-time-baked capsule
 * directory. This builds a heap-only, single-entry CapsuleDirHeader +
 * CapsuleDesc + CapsuleNameEntry + arena from that region and hands it to
 * the existing, unmodified capsule_birth_baby() -- no new birth mechanism,
 * per §F.6's own trace ("capsule_birth_baby() is already generic").
 *
 * Does not verify the caller has already run CERTVERIFY -- that's the
 * caller's responsibility (WIREBIND, not yet built). This function's own
 * job is narrow: read the region, construct the directory, birth it.
 */

#ifndef STARKERNEL_CAPSULE_RUNCAP_H
#define STARKERNEL_CAPSULE_RUNCAP_H

#ifdef __STARKERNEL__

#include <stdint.h>
#include "starkernel/capsule_run.h"   /* CapsuleRunResult */
#include "starkernel/vm_uuid.h"       /* VMUuid */
#include "starkernel/homeblocks_sig.h" /* homeblocks_sig_t */

struct blkio_dev;

/**
 * capsule_runcap_birth - Birth a VM from a home-blocks drive's own
 * identity_src region.
 *
 * Reads sig->identity_src_devblocks devblocks starting at
 * sig->identity_src_offset. The first devblock is the identity's own
 * user_identity_seed_t record (MINT, §F.8) and is skipped here -- RUNCAP
 * only cares about the FORTH source that follows it. Refuses cleanly
 * (CAPSULE_RUN_ERR_INVALID) if identity_src_offset is 0 (never minted) or
 * identity_src_devblocks < 2 (no source content beyond the seed record).
 *
 * The heap-allocated directory/descriptor/name/arena are never freed --
 * deliberate, matching kernel_main.c's own compile-time-directory-to-heap
 * copy at Mama's own birth (also never freed): a VM's IDENTITY exec reads
 * directly from this arena, and nothing in this codebase frees capsule
 * arenas after a successful birth today.
 *
 * @param dev         Already-open block device for the attached drive.
 * @param sig         Already-verified homeblocks_sig_t read from it.
 * @param vm_name     Symbolic name for the new VM (becomes both the
 *                    capsule's own single directory entry name and the
 *                    VM registry name).
 * @param out_vm_id   Output: assigned VM ID.
 * @param out_vm_ctx  Output: new VM context (may be NULL if not needed).
 * @return CAPSULE_RUN_OK on success, error code otherwise.
 */
CapsuleRunResult capsule_runcap_birth(
    struct blkio_dev      *dev,
    const homeblocks_sig_t *sig,
    const char             *vm_name,
    VMUuid                 *out_vm_id,
    void                  **out_vm_ctx
);

#endif /* __STARKERNEL__ */

#endif /* STARKERNEL_CAPSULE_RUNCAP_H */