Every object that receives implementation or matching work must maintain one
Markdown ledger in this directory. The filename is the object name with
_obj.md, for example players_obj.md.
General techniques that apply across translation units belong in
docs/exact_match_acceleration_playbook.md; object-specific measurements stay
in the individual ledger.
The purpose is to make matching work cumulative. A new lane must be able to
distinguish an untried evidence-backed source shape from a spelling that has
already compiled to the same bytes.
Required contents
Each ledger must include:
Scope and provenance
source translation unit and target object;
exact compiler identity and flags;
target-build provenance used for names, layouts, or source topology.
Validated baseline
exact/total function count and padded code bytes;
exact/total data sections and bytes;
for every residual: target/base size, relocation count, normalized hash,
and first meaningful divergence.
Accepted controls
the source shapes retained in production;
why each shape is supported by binary or provenance evidence.
Experiment matrix
every meaningful source shape tested;
resulting size, relocations, normalized hash, first divergence, and
sibling-regression result;
whether it was retained or reverted.
Do-not-repeat list
equivalent spellings or compiler-control attempts already exhausted;
unsafe or prohibited techniques.
Residual classification
source/topology, ABI/register, scheduling, ownership/relocation, data, or
unresolved;
clearly separate measured fact from inference.
Reopen criteria
the exact new evidence that would justify spending another lane.
Disposition
strict exact and eligible for Matching, still active, or rigorously
parked;
never grant credit from a fuzzy percentage, equal size alone, or semantic
plausibility.
Lane rules
Update the ledger after every bounded experiment batch, not only at handoff.
Rebuild with XDK 3911 and the repository flags after each retained change.
Gate every function and owned data section with the hardened comparator.
Run the whole-translation-unit regression sweep before committing.
Revert failed source shapes immediately.
Do not use inline assembly, volatile byte forcing, undefined behavior,
object-byte patches, or compiler-flag changes.
A parked residual must preserve enough evidence for another agent to
reproduce the classification without redoing the full search.
Label a defect BUG (original) only when January binary/source evidence
proves the defective behavior belongs to the original game. A mistake or
omission in our reconstruction is not an original bug. Preserve proven
original behavior in the matching build and document the corrected-build
alternative in a comment without changing the matching token/line shape.
When retroactively documenting an old lane, state which experiment details
were not preserved. Never manufacture source variants, hashes, or outcomes
to make a historical matrix look complete.
