rrt/docs/function-map.md

Function Map

The function map is the canonical ledger for reverse-engineering progress. It should be updated even when the understanding is partial, because partial structure is still useful if it is explicit about confidence.

The handbook index in docs/README.md should stay high-level. Per-pass function additions and renames belong here and in the derived export artifacts, not in the README. High-level control-loop and subsystem flow belongs in the split atlas under docs/control-loop-atlas/, with docs/control-loop-atlas.md serving as the compatibility index and this file staying function-centric.

Canonical Schema

The committed CSV header is:

address,size,name,subsystem,calling_convention,prototype_status,source_tool,confidence,notes,verified_against

Field meanings:

• address: virtual address in the canonical 1.06 executable
• size: best current size in bytes; leave blank if unknown
• name: current best function name
• subsystem: coarse ownership bucket such as startup, bootstrap, support, render, audio, ui, map, save, network
• calling_convention: cdecl, stdcall, thiscall, fastcall, or unknown
• prototype_status: unknown, inferred, or confirmed
• source_tool: primary tool or source behind the current row
• confidence: integer from 1 to 5
• notes: short justification, ambiguity, or follow-up
• verified_against: hash, runtime trace, second tool, or other corroboration

Update Rules

• New rows must always include address, name, subsystem, source_tool, and confidence.
• Prefer names in the shape owner_verb_object[_qualifier].
• Prefer one primary verb, one primary object, and at most one qualifier.
• If a rename is speculative, state that directly in notes.
• When two tools disagree on function boundaries, preserve the ambiguity in notes instead of hiding it.
• Prefer one row per concrete function, not per guessed feature.
• Prefer try_ for best-effort helpers that may fall through without mutation or publication.
• Prefer apply_ when a helper commits one selected policy or state transition.
• Reserve evaluate_ for read-heavy helpers that classify or score state without committing the later action themselves.
• Prefer one stable family noun once a transient runtime structure is grounded.
• Use queue_node for transient linked-list allocations, and reserve record for persisted rows or document-style payloads.
• Prefer startup_company over company_start when the object is the newly started company.
• Prefer participial qualifiers such as _ignoring_territories over _with_*_ignored once the side condition is grounded.
• Drop filler tails such as _lanes once a broader owner is grounded well enough to carry the family directly.
• Prefer _and_optionally_ over _with_optional_ when a helper may take one secondary path but the main owner is still singular.
• Treat _and_, _with_, _if_, and _via_ as fallback tools for still-uncertain seams, not the default naming style.
• Raw offset tails such as field_0xNN are acceptable for direct accessors and low-confidence rows, but should be replaced once a grounded semantic field name exists.

Starter Subsystems

Use these buckets until the map needs finer structure:

• startup
• bootstrap
• shell
• support
• ui
• render
• audio
• input
• network
• filesystem
• resource
• map
• scenario
• save
• simulation
• unknown

Verification Sources

Examples for verified_against:

• sha256:01b0... + objdump
• ghidra + rizin
• ghidra + string xref
• runtime trace under winedbg

Exit Criteria For The Milestone

The first function-mapping milestone is complete when the repo has:

• a stable starter map for the canonical binary
• named anchors for startup and a few obvious subsystem gateways
• enough notes and exports that a future session can continue without rediscovery