/*
  StarForth — Steady-State Virtual Machine Runtime

  Copyright (c) 2023–2026 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.
*/

/**
 * vm_log_buffer.h - a VM's log records, on their way to Artemis's log ring
 * (FABRIC-3.md §XXXVIII, 2026-10-14; Captain Bob's rulings that day).
 *
 * Every record log_message() makes while a VM is the one attributed
 * (vm_log_attributed_vm()) is packed into that VM's own buffer (VM.log_buf).
 * The buffer goes to Artemis as one kernel-Hermes message (type
 * SK_HERMES_MSG_TYPE_LOG_BATCH) on LOG-FLUSH, when the next record would not
 * fit, and at once after an ERROR record. Artemis takes it on her own turn
 * (the one delivery path, §XXXVI) and writes each record to her log ring
 * (log_region.c), its source the VM the kernel stamped as sender -- never a
 * name the sender supplies. Records that cannot be sent yet (Artemis not
 * live, the send refused) are counted, never silently lost: the next flush
 * that can be sent carries "N log records not sent" first.
 *
 * Record layout in a buffer and a batch: level (1 byte), timestamp (8,
 * shim.c's KRELTSC base), length (2), then the text.
 */

#ifndef STARKERNEL_VM_LOG_BUFFER_H
#define STARKERNEL_VM_LOG_BUFFER_H

#ifdef __STARKERNEL__

#include <stdint.h>
#include "starkernel/vm_uuid.h"

struct VM;

/* Adds one record to vm's buffer (flushing first if it would not fit, and
 * after it if it is an ERROR). Never logs; a call made while the buffer is
 * already being worked on (a log line from inside a flush) is dropped and
 * counted. */
void vm_log_buffer_add(struct VM *vm, uint8_t level, uint64_t timestamp,
                       const char *msg, uint32_t len);

/* Sends vm's buffer to Artemis. Returns the number of records sent, 0 when
 * there was nothing to send, -1 when it could not be sent (the records are
 * then counted in vm->log_lost). */
int vm_log_buffer_flush(struct VM *vm);

/* Artemis's side, called by sk_hermes_drain_checkpoint() for a
 * SK_HERMES_MSG_TYPE_LOG_BATCH message, in her own context: writes each
 * record to the log ring, its source the sender `from`. Returns the
 * number written; -1 if vm is not Artemis (the batch is then dropped). */
int vm_log_batch_deliver(struct VM *vm, VMUuid from,
                         const uint8_t *payload, uint32_t payload_len);

#endif /* __STARKERNEL__ */

#endif /* STARKERNEL_VM_LOG_BUFFER_H */