Rebuilding GNU Chess for Ensemble 1.x - port release 0.2
=======================================================

GNUCHESS.GEO is already compiled. These steps are for developers.
Run commands from this SOURCE directory. Python 3 and NASM 2.16+ are needed.

QUICK REBUILD, NO GEOS SDK
-------------------------
    NASM=/path/to/nasm sh port1/rebuild.sh

Output: port1/low_memory/dist/rebuilt/GNUCHESS.GEO
This reproduces the released application byte for byte. It uses the included
genuine engine intermediate port1/engine8086/build/geos/gnuchess.geo, compiled
from the included C++ source with Open Watcom -0. It assembles the native shell,
runtime and fixed call bridge, builds 1.x objects/classes and emits the native
executable layout with engine code marked movable and swappable.

FULL ENGINE SOURCE BUILD
------------------------
Install the public PC/GEOS source, SDK, Open Watcom 2 Linux tools and NASM.
Tool provenance is in port1/toolchain/environment.json. Set your own paths:

    export ROOT_DIR=/path/to/pcgeos-source
    export GEOS_SDK=/path/to/pcgeos-sdk
    export WATCOM=/path/to/openwatcom
    export NASM=/path/to/nasm
    sh port1/rebuild.sh --compile-engine

If GEOS_HOST_TOOLS is unset, the included bootstrap builds GOC and Glue from
ROOT_DIR/Tools with the host64 and empty-debug-map fixes used for this build.
Otherwise set GEOS_HOST_TOOLS to the directory containing your goc and glue.
The full route compiles all 30 adapted engine translation units, builds the
intermediate geode, extracts bridge offsets through wdis, then builds the
native 1.x application. Both routes were run for release 0.2 and produced:

796ba70122e22276bbeac16ef55fa9bed87d525419072446df3afff6137d5c62

See ../EVIDENCE/v0.2/rebuild-report.json and the two rebuild logs.

SOURCE MAP
----------
port1/engine8086/src/engine     Adapted GNU Chess 6.3.0 engine used here.
port1/engine8086/src/geos       Intermediate build interface.
port1/low_memory/ui/native.asm Native Ensemble 1.x message handlers/drawing.
port1/low_memory/ui/artwork.inc Included native 4-bit chess-piece artwork.
port1/low_memory/engine_native/runtime8086.asm
                              Native string/memory/math compatibility.
port1/low_memory/generate_thunks.py
                              C-stack-transparent code lock/return bridge.
port1/low_memory/audit/native_objects.py
                              Native objects, window, buttons and view.
port1/low_memory/build_port.py Native resource/relocation/executable builder.
port1/low_memory/rebuild.sh    Release 0.2 end-to-end build entry point.
port1/rebuild.sh              Forwards to the release 0.2 build entry point.
work/gnuchess-pcgeos          Original supplied adaptation, vendor snapshot,
                              artwork, licenses and host engine tests.

Older port1/ui and port1/build_port.py sources are retained as the fixed-code
baseline. Use the low_memory build for the current release.

MEMORY AND CALLING CONVENTION
-----------------------------
Resources 26-54 are read-only shared code with flags 0x0a50: preloaded,
movable, swappable and nondiscardable. The supplied 1.2 MemLock rejects
discarded resources, so discardable flags must not be substituted.
Resource 2 remains fixed because the engine uses a raw function pointer to it.
Engine data remains fixed because the compiled engine retains raw pointers.

Fixed resource 61 has 120 entry thunks and a common return cleanup. Each call
locks the target handle, replaces only its original far return address, and
jumps into the target. RETF and RETF N therefore keep the original C/Pascal
argument layout. Cleanup preserves returned registers/flags, unlocks the
completed target and resumes the original caller. Enclosing caller resources
remain locked until their own returns. Context depth is limited to 128.

This bridge requires the compiled engine ABI: DS is the private DGROUP on
entry/return, and engine calls occur on the process thread. It is not a general
bridge for arbitrary routines returning a different DS. The single-instance
header attributes are 0x9200. DGROUP initialization plus stack is 0xf000 bytes.

The engine and arithmetic runtime use 8086 instructions so live state survives
the old kernel's 16-bit context switch. The frozen native shell includes 386
conditional jumps, so this complete binary requires a 386 or later CPU.

TESTS
-----
Install Unicorn for the CPU tests. From SOURCE:

    python3 port1/low_memory/tests/test_engine.py port1/low_memory/dist/rebuilt/GNUCHESS.GEO
    python3 port1/low_memory/audit/test_thunk_abi_independent.py

The engine test executes the actual converted machine code, moves code blocks
between unlocked calls and poisons stale locations. It covers initialization,
illegal-move immutability, replies, depth 4, Undo, self-play and balanced locks.
The independent bridge harness covers C/Pascal returns, stack/register/FLAGS
preservation, nesting and fatal failure guards.

CPU tests stub kernel boundaries. Actual GEOS acceptance, memory measurements
and screenshots are recorded separately under ../EVIDENCE/v0.2.
The existing host ASan/UBSan tests and arithmetic helper tests concern the
unchanged engine/runtime; their reports remain in ../EVIDENCE.

LICENSING
---------
GPL version 3 or later, with retained Apache-2.0 notices for PC/GEOS portions.
The external SDK/compiler tools and the user's Ensemble runtime are excluded.
The 288-byte native header template is executable metadata, not a system library.
