/*
  StarForth — Steady-State Virtual Machine Runtime

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

  This file is part of the StarForth project.

  Licensed under the StarForth License, Version 1.0 (the "License");
  you may not use this file except in compliance with the License.

  You may obtain a copy of the License at:
      https://github.com/star.4th@proton.me/StarForth/LICENSE.txt

  This software is provided "AS IS", WITHOUT WARRANTY OF ANY KIND,
  express or implied, including but not limited to the warranties of
  merchantability, fitness for a particular purpose, and noninfringement.

  See the License for the specific language governing permissions and
  limitations under the License.
*/

/**
 * log_attrib.h - "Which VM is currently executing" for log persistence
 * attribution (FABRIC-3.md §XXVI follow-on, Step 4, 2026-09-13)
 *
 * log_message() (shim.c) is a global function called from hundreds of
 * existing sites -- most with no VM in scope at all (boot, PCI, xHCI,
 * driver code). Rather than thread a VM parameter through every one of
 * those call sites (a large, invasive change for no benefit to the ones
 * that genuinely have no VM), vm_interpret() (vm_core.c, the single
 * dispatch entry point for ALL FORTH execution -- interactive lines,
 * LOAD'd block content, and every VM-EXEC/MSG-DELIVER dispatch into a
 * target VM) sets this at entry and restores the previous value at exit,
 * save/restore style so nested vm_interpret() calls (VM-EXEC dispatching
 * into a different VM's own dictionary, mid-interpret) attribute
 * correctly to whichever VM is actually running at the moment
 * log_message() fires -- not the outermost caller.
 *
 * NULL means "no VM is currently interpreting" -- boot sequence, PCI/
 * xHCI/driver code, anything running outside a vm_interpret() call frame.
 * log_message()'s own persistence hook (shim.c) treats NULL as the fixed
 * "HADES" pseudo-source, matching the console's own existing
 * "[HADES][LEVEL]" prefix convention for exactly this class of message.
 */

#ifndef STARKERNEL_LOG_ATTRIB_H
#define STARKERNEL_LOG_ATTRIB_H

#ifdef __cplusplus
extern "C" {
#endif

struct VM;

/* vm_log_attributed_vm - The VM whose dictionary context is currently
 * executing, or NULL if none (see this header's own doc comment). */
struct VM *vm_log_attributed_vm(void);

#ifdef __cplusplus
}
#endif

#endif /* STARKERNEL_LOG_ATTRIB_H */