deepened understanding

docs/remorse-cpp-compatibility-header-draft.md

@@ -0,0 +1,159 @@
+# Remorse C++ Compatibility Header Draft
+
+## Purpose
+
+This note defines the minimum compatibility/support layer that future hand-maintained Remorse C++ skeletons should target.
+
+It is not a final header and it is not a compiler lock-in decision. It is a draft contract so early class-emission work does not silently drift into host-only modern C++ assumptions.
+
+This note should stay paired with [docs/remorse-rebuild-abi-notes.md](docs/remorse-rebuild-abi-notes.md).
+
+## Why This Layer Is Needed
+
+Current rebuild notes already make three constraints clear:
+
+- Track A original-style executable reconstruction remains in scope
+- the executable is shaped by segmented pointers and far-call conventions
+- host compilation success is not enough if layout, slot order, or call shape drift
+
+That means the first C++ skeletons should compile against a compatibility layer that makes these constraints explicit even before the exact compiler/toolchain decision is closed.
+
+## Minimum Header Categories
+
+### 1. Exact-width integer aliases
+
+Needed because:
+
+- field maps are being recovered by offset
+- slot/value and save/load structures use exact-width arithmetic
+- sign extension versus zero extension matters repeatedly in the current notes
+
+Current draft surface:
+
+```cpp
+using u8 = std::uint8_t;
+using s8 = std::int8_t;
+using u16 = std::uint16_t;
+using s16 = std::int16_t;
+using u32 = std::uint32_t;
+using s32 = std::int32_t;
+```
+
+### 2. Packing controls
+
+Needed because:
+
+- object and save-state layouts are currently tracked by exact offsets
+- future vtable-bearing structs must not silently pick host-default padding
+
+Current draft surface:
+
+```cpp
+#define CR_PACK_PUSH_1
+#define CR_PACK_POP
+#define CR_PACKED
+```
+
+The final spelling can change per compiler. The important part is that early source slices already depend on named packing controls rather than ad hoc pragmas in every file.
+
+### 3. Calling-convention markers
+
+Needed because:
+
+- later method and helper promotion will need to distinguish ordinary helpers from call-shape-sensitive surfaces
+- Track A may need explicit far/near or compiler-family-specific conventions
+
+Current draft surface:
+
+```cpp
+#define CR_CDECL
+#define CR_STDCALL
+#define CR_THISCALL
+#define CR_FARCALL
+```
+
+`CR_FARCALL` is intentionally placeholder-level today. The current value is in making far-call-sensitive surfaces visible in source, not in pretending the final compiler spelling is already known.
+
+### 4. Segmented pointer helper types
+
+Needed because:
+
+- several notes still preserve segment:offset provenance directly
+- owner-loaded VM source pairs and some callback/resource lanes should not be flattened too early
+
+Current draft surface:
+
+```cpp
+struct FarPtr16 {
+    u16 offset;
+    u16 segment;
+};
+
+template <typename T>
+struct FarPtr {
+    u16 offset;
+    u16 segment;
+};
+```
+
+Current rule:
+
+- use these first as evidence-preserving placeholders, not as proof that final emitted code must literally use this exact host representation everywhere.
+
+### 5. Vtable and slot-order helpers
+
+Needed because:
+
+- current family notes still treat slot order as evidence, not cosmetics
+- later MCP or hand-authored promotion should preserve raw order even when names are provisional
+
+Current draft surface:
+
+```cpp
+#define CR_VSLOT(index)
+```
+
+This can stay documentation-only at first if needed. The point is to keep raw slot numbering visible in provisional class headers.
+
+## First Skeleton Rules
+
+When the first class family is emitted to source, the compatibility header should enforce these rules:
+
+1. every field uses exact-width aliases
+2. every packed layout is explicit
+3. every unresolved far/segment-sensitive pointer uses a named placeholder type
+4. every provisional virtual surface keeps raw slot order visible
+5. Track A-only assumptions are marked instead of being silently baked into Track B-style cleanup
+
+## Families Most Likely To Need This Immediately
+
+1. `EntityDispatchEntry`
+2. `SpriteNode`
+3. `EntityVmRuntime`
+4. `EntityVmOwnerResource`
+5. `EntityVmContext`
+
+`Entity` will also need it, but its family split is large enough that it should probably not be the first source-emission pilot.
+
+## What This Draft Deliberately Avoids
+
+- picking one final compiler family now
+- pretending near/far semantics are already solved
+- turning unresolved imported-runtime calls into polished modern interfaces
+- flattening segment:offset provenance into generic host pointers too early
+
+## Proposed Next Step
+
+Once the first pilot family is chosen, convert this note into a real minimal header with:
+
+- exact-width aliases
+- packing markers
+- calling-convention placeholders
+- one segmented-pointer placeholder type
+- one comment block explaining Track A versus Track B expectations
+
+## Bottom Line
+
+The compatibility header should exist before the first C++ skeleton is emitted, not after.
+
+That keeps early source work honest and preserves the option of an original-style rebuild instead of quietly drifting into a pure host-port codebase.