/*
  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_console.h - Bare console-VM birth (FABRIC-3.md Phase F,
 * 2026-08-28): a minimal VM whose only job is loading
 * common:messaging.4th and being the physical REPL's relay target
 * (sk_repl_dispatch_line(), repl.c) for a paired user VM
 * (capsule_runcap_birth(), capsule_runcap.h). Not identity-bearing
 * content -- no thumbdrive read, fixed embedded source, same
 * heap-built-single-entry-directory shape RUNCAP already established
 * (§F.6/§F.18), just with compile-time content instead of a devblock
 * read.
 */

#ifndef STARKERNEL_CAPSULE_CONSOLE_H
#define STARKERNEL_CAPSULE_CONSOLE_H

#ifdef __STARKERNEL__

#include "starkernel/capsule_run.h"
#include "starkernel/vm_uuid.h"

/**
 * capsule_console_birth - Birth a bare console VM.
 *
 * @param console_name  Symbolic name for the new VM -- by convention
 *                       the same name a user's own identity uses (e.g.
 *                       "CaptBob"); sk_repl_dispatch_line() looks for a
 *                       live "<name>~user" counterpart to decide
 *                       whether a given active VM is a console.
 * @param out_vm_id      Output: assigned VM ID.
 * @param out_vm_ctx     Output: new VM context (may be NULL).
 * @return CAPSULE_RUN_OK on success, error code otherwise.
 */
CapsuleRunResult capsule_console_birth(const char *console_name,
                                        VMUuid *out_vm_id, void **out_vm_ctx);

#endif /* __STARKERNEL__ */

#endif /* STARKERNEL_CAPSULE_CONSOLE_H */