feat(log): LOG-FLUSH -- a VM's log records reach Artemis's log ring; and the ring keeps its order when it grows

FABRIC-3 SXXXII.4's deferred LOG-FLUSH, built to the 2026-10-14 rulings (SXXXVIII): everything a VM logs, at or above the log level, goes into its own buffer; it goes to Artemis on LOG-FLUSH, when full, and at once on an ERROR, as one kernel-Hermes LOG_BATCH message she writes on her own turn, the source being the sender the kernel stamped. Records that cannot go yet are counted and reported with the next flush. LOG-SHOW (Hera only) reads the ring back -- it had no reader. Found by the first test that filled it: ring growth overwrote the oldest record and put blank slots inside the live range. Fixed test first. Three ISAs: POST 1052 passed; new parity baseline word_count=526 hash=0x82f4ae7cb2e2d424 (deliberate). CLAUDE.md: Phase 8 PKI closed. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-14 12:10:01 -04:00
parent 5e26fad30d
commit 4da370f492
35 changed files with 91102 additions and 15 deletions
@@ -0,0 +1,63 @@
+/*
+  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 */