Crusader_Decomp/docs/remorse-rebuild-abi-notes.md

Remorse Rebuild ABI Notes

Purpose

This note records the current ABI, memory-model, and toolchain constraints that should shape any future Remorse source reconstruction.

The class-lifting notes answer what the objects probably are. This note answers what the rebuilt source must still respect if it aims to become a working executable rather than only readable C++.

Current Baseline

The live target is not a flat modern Win32 program.

Current verified binary facts:

• DOS target
• 16-bit protected-mode environment
• Phar Lap 286 DOS-Extender (RUN286)
• bound MZ -> NE executable
• heavy use of inter-segment and external CALLF fixups

That means the default safe assumption is:

• segmented code/data model matters
• near/far calls matter
• pointer width and calling convention details matter
• loader/runtime expectations matter

Hard Constraints Already Visible In The Binary

1. Segmented addressing is real, not presentation noise

Evidence:

• executable format is MZ -> NE
• raw import behavior collapses unresolved calls to 0000:ffff until NE fixups are applied
• repaired raw import had thousands of internal literal CALLF sites patched to real segment:offset targets
• the notes repeatedly distinguish far pointers, segment:offset storage, and per-segment relocation behavior

Practical implication:

• a rebuild target that ignores far calls and far data pointers too early will drift away from the original executable model

2. Function boundaries and external calls are loader-sensitive

Evidence:

• CALLF 0000:ffff is a placeholder used by the NE loader for real inter-segment/external targets
• unresolved far thunk behavior in raw import is explicitly not a real dispatcher

Practical implication:

• source emission must preserve which calls are logically intra-object methods and which ones are ABI-significant far calls or imported runtime/library calls

3. Runtime/library layer is not trivial glue

Evidence:

• large Phar Lap runtime/extender segments remain part of startup and low-level system behavior
• CRT wrappers and formatter/runtime helpers are explicitly identified
• MetaWare High C formatting/runtime wrappers are present in the notes

Practical implication:

• the original or near-original compiler/runtime environment matters enough that just compile with a modern compiler is not a safe early assumption for an original-style rebuild

4. Object layout is tightly coupled to exact field offsets

Evidence:

• major gameplay and UI families are still being recovered by exact offsets
• VM/runtime helpers, dispatch entries, and entity families all depend on stable field positions

Practical implication:

• class lifting must preserve packed layout discipline and exact-width integer choices from the start

Current Best Toolchain Read

This is still a working model, not a closed historical claim.

High-confidence environment facts

• DOS protected mode under Phar Lap 286 extender
• NE executable image
• runtime/CRT evidence compatible with MetaWare High C presence in at least part of the binary toolchain story

What remains open

• exact original compiler version
• exact memory-model flags used for all modules
• exact calling-convention mapping for each object family
• exact linker/build recipe needed to reproduce compatible NE output

Recommended Rebuild Tracks

Track A: Original-style executable reconstruction

If the goal is to rebuild something close to the shipped executable model, the source must preserve:

• segmented pointer distinctions
• explicit near/far calling boundaries where needed
• exact struct packing
• compatible CRT/runtime assumptions
• executable/resource layout expectations

This is the stricter track.

Track B: Behaviorally equivalent source port

If the goal is instead a working engine/game rebuild using the original data with equivalent behavior, then the source can relax some ABI constraints later.

But even on this track, the early reverse-engineering output should still preserve ABI facts long enough that the project can make an informed choice instead of accidentally forcing itself into a port.

Source-Level Rules To Adopt Early

Any future generated or handwritten code should default to these constraints:

Integer widths

• use explicit fixed-width integer types everywhere possible
• do not use plain int, long, or compiler-default enum width as semantic types in the first pass

Layout control

• keep a visible packing strategy for recovered structs
• record uncertain padding explicitly rather than letting the compiler invent it silently

Pointer model

• keep far-pointer distinctions visible in the type system or wrapper layer
• do not immediately collapse all pointers to one flat host pointer type if Track A remains in scope

Calling conventions

• keep calling convention annotations explicit in working notes and emitted skeletons
• do not assume one modern host calling convention is an adequate stand-in for every recovered method or helper

Virtual dispatch

• preserve raw slot order in provisional vtable types
• do not rename or reorder slots to look cleaner before the mapping is stable

Candidate ABI Support Layer

The first C++ source slices should probably compile against a small compatibility layer rather than raw host C++ alone.

Current likely categories:

• exact-width integer typedefs
• far/near pointer wrappers or placeholder abstractions
• packing macros or pragmas
• calling-convention macros
• segmented address helper types for debugging and trace comparison
• imported runtime service shims for file, memory, and platform calls

Immediate Compiler/Runtime Questions To Close Later

These are the most useful next ABI questions for the repo:

1. Which compiler/runtime signatures in the binary most strongly identify the original toolchain family and version?
2. Which current methods clearly require far-call semantics even after class lifting?
3. Which object families can safely be emitted as host-side plain structs first, and which still need explicit segmented-pointer wrappers?
4. What is the narrowest executable milestone that can validate calling conventions and struct layout before whole-program reconstruction is attempted?

Practical Risk List

Risk: pretty C++ that cannot rebuild the game

Cause:

• class lifting done without ABI discipline

Mitigation:

• keep this note paired with the class-layout notes and require exact-width/packing/calling-convention placeholders in early skeletons

Risk: false confidence from host compilation success

Cause:

• code compiles under a modern compiler but no longer matches segmented runtime behavior

Mitigation:

• define compile success and behavioral/ABI success as separate milestones

Risk: loss of far-call/import provenance

Cause:

• unresolved thunk placeholders or loader-patched calls get flattened into generic helper names

Mitigation:

• preserve call provenance in notes and later exports, especially for methods that only look local after fixup repair

Recommended Near-Term Documentation Follow-Ups

1. collect all current compiler/runtime fingerprints into one evidence note
2. add an ABI concerns section to future class-layout notes when a family uses far pointers or segmented ownership directly
3. draft the first minimal compatibility header for future C++ skeletons once the first class family is selected for source emission

Current Bottom Line

The project is now documented well enough to start class lifting, but not well enough to safely emit clean modern C++ without guardrails.

The safest present rule is:

• keep object recovery aggressive
• keep ABI assumptions conservative
• keep Track A and Track B separate in every future source milestone