From 2c2332c0a9514897ea4ca4e30e47442bcab02bc5 Mon Sep 17 00:00:00 2001
From: Roland Conybeare <rconybeare@gmail.com>
Date: Wed, 18 Mar 2026 09:50:01 -0400
Subject: [PATCH] xo-gc: + MutationLogEntry.hpp [WIP]

---
 include/xo/gc/MutationLogEntry.hpp | 47 ++++++++++++++++++++++++++++++
 1 file changed, 47 insertions(+)
 create mode 100644 include/xo/gc/MutationLogEntry.hpp

diff --git a/include/xo/gc/MutationLogEntry.hpp b/include/xo/gc/MutationLogEntry.hpp
new file mode 100644
index 0000000..01c3666
--- /dev/null
+++ b/include/xo/gc/MutationLogEntry.hpp
@@ -0,0 +1,47 @@
+/** @file MutationLogEntry.hpp
+ *
+ *  @author Roland Conybeare, Mar 2026
+ **/
+
+#pragma once
+
+#include "GCObject.hpp"
+
+namespace xo {
+    namespace mm {
+
+        /** @brief Track a cross-generational pointer
+         *
+         *  GC must update pointer when collecting space that target occupies
+         *
+         *  Design notes:
+         *  - parent must be located at the beginning of an allocation,
+         *    (so that it's immediately preceded by allocation header)
+         *  - destination can be something like
+         *      obj<AGCObject>
+         *    but also something else such as
+         *      {obj<AType>, obj<ASyntaxStateMachine>, ..}
+         *  - for collector need to traverse data pointer *data
+         **/
+        class MutationLogEntry {
+        public:
+            MutationLogEntry(void * parent, void ** p_data, obj<AGCObject> snap);
+
+        private:
+            /** address of object containing logged mutation **/
+            void * parent_ = nullptr;
+            /** address of target member of object at address @ref parent_,
+             *  driving this log entry.
+             **/
+            void ** p_data_ = nullptr;
+            /** AGCObject i/face pointer, asof assignment responsible for this log entry.
+             *  If *p_data_ matches snap_.data(), then AGCObject interface is snap_.iface().
+             *  Otherwise log entry has been superseded by another assignment.
+             **/
+            obj<AGCObject> snap_;
+        };
+
+    } /*namespace mm*/
+} /*namespace xo*/
+
+/* end MutationLogEntry.hpp */