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