# 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:

```text
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`.
- 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.

## 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