Feature/1276 (#762)

* embedded member access by offset

* compact o_list + integration

---------

Co-authored-by: Wojtek <wskozlowski@dbzero.io>

Author: wskozlowski

AGENTS.md

@@ -47,6 +47,10 @@ Types derived from `v_object` should follow the project-wide constructor pattern
 - New durable instances are constructed from `Memspace &` plus any type-specific creation arguments.
 - Existing durable instances are reopened from `mptr` plus any type-specific runtime dependencies.
 
+### Overlaid type inheritance
+
+Variable-size overlaid types that derive from another overlaid type must use `db0::o_ext<Derived, BaseOverlay, VER, STORE_VER>` rather than directly inheriting from an `o_base`-derived overlay such as `o_list`. Direct inheritance bypasses `o_ext` sizing, version, and dynamic-area handling and can corrupt overlaid layout assumptions.
+
 ### C++ style
 
 - Use camelCase for local helper variables, lambdas, and method names in C++ code.

design/IMMUTABLE_OBJECTS_DESIGN.md

@@ -106,10 +106,13 @@ Implementation requirements:
 - Field retrieval returns an object view of the root object that exposes only the nested fields for read access.
 - The view must maintain the lock or lifetime guard of the top-level object while nested fields are accessed.
 - References to embedded objects point to a memory location inside the root allocation and also carry the nested member offset. The offset may be deeply nested.
+- Embedded object offsets are byte offsets relative to the persisted `o_immutable_object` data structure overlaid on the root allocation, not relative to the C++ `ObjectImmutableImpl` wrapper instance.
 - The lifecycle of an embedded object is tied to the root instance because the root owns the allocation containing the full embedded tree.
 - The embedded member is identified by its own address, but that address is inside the allocation and is not the allocation start.
 - The allocator must be able to recover allocation metadata from an inner address. This allows embedded object addresses to use the same 50-bit representation as regular object addresses.
 - A parent object can still be referenced by the parent allocation address.
+- Root immutable objects store an exact compact index of valid nested embedded-object offsets. Lookup by offset must validate against this index and raise a bad-address error for invalid, out-of-range, or non-object offsets.
+- The offset index uses packed integer encoding grouped by packed size class so offsets remain compact while supporting logarithmic exact membership checks. Most offsets are expected to fit in 3-4 packed bytes, but the representation must support larger offsets.
 
 ## Object Views
 

src/dbzero/bindings/python/embedded/EmbeddedObject.cpp

@@ -15,6 +15,7 @@
 #include <dbzero/object_model/class/Class.hpp>
 #include <dbzero/object_model/class/ClassFactory.hpp>
 #include <dbzero/object_model/dict/o_py_dict.hpp>
+#include <dbzero/object_model/object/ObjectInitializer.hpp>
 #include <dbzero/object_model/object/ObjectImmutableImpl.hpp>
 #include <dbzero/object_model/object/o_embedded_object.hpp>
 #include <dbzero/object_model/set/o_py_set.hpp>
@@ -629,6 +630,7 @@ namespace db0::python
         if (PyObject_GC_IsTracked(object)) {
             PyObject_GC_UnTrack(object);
         }
+        InitManager::instance.tryCloseInitializer(object->ext());
         object->destroy();
         new ((void *)const_cast<MemoImmutableObject::ExtT *>(&object->ext()))
             EmbeddedObjectRef(rootObject, &embeddedObject, std::move(type));

src/dbzero/core/serialization/Types.cpp

@@ -32,10 +32,23 @@ namespace db0
 		std::copy(data.data(), data.data() + m_bytes, &m_buf);
 	}
 
-    o_binary::o_binary(std::size_t size, void (*write)(void *, const void *), const void *source)
+    o_binary::o_binary(
+        std::size_t size,
+        void (*write)(void *, const void *, db0::object_model::EmbeddedObjectOffsetCollector *),
+        const void *source
+    )
+        : o_binary(size, write, source, nullptr)
+    {
+    }
+
+    o_binary::o_binary(
+        std::size_t size,
+        void (*write)(void *, const void *, db0::object_model::EmbeddedObjectOffsetCollector *),
+        const void *source, db0::object_model::EmbeddedObjectOffsetCollector *context
+    )
         : m_bytes(size)
     {
-        write(&m_buf, source);
+        write(&m_buf, source, context);
     }
 
 	o_binary &o_binary::operator=(const o_binary &binary) 

src/dbzero/core/serialization/Types.hpp

@@ -8,6 +8,11 @@
 #include <dbzero/core/serialization/Fixed.hpp>
 #include <dbzero/core/compiler_attributes.hpp>
 
+namespace db0::object_model
+{
+    struct EmbeddedObjectOffsetCollector;
+}
+
 namespace db0 
 
 {
@@ -116,7 +121,19 @@ DB0_PACKED_BEGIN
 
         o_binary(const std::vector<std::byte> &);
 
-        o_binary(std::size_t size, void (*write)(void *, const void *), const void *source);
+        // Optional context lets writer-backed payloads receive construction-only state.
+        // A null context is used by measurement and ordinary copy paths.
+        o_binary(
+            std::size_t size,
+            void (*write)(void *, const void *, db0::object_model::EmbeddedObjectOffsetCollector *),
+            const void *source
+        );
+
+        o_binary(
+            std::size_t size,
+            void (*write)(void *, const void *, db0::object_model::EmbeddedObjectOffsetCollector *),
+            const void *source, db0::object_model::EmbeddedObjectOffsetCollector *context
+        );
 
     public:
         /**