# Host API map

Source-level finding F21, 2026-10-21. Baseline: build `2016-03-10-c`; full archive/member identities are in [the source map](../assets/analysis/source-map.json). The [API index](API_INDEX.md) enumerates all Core endpoints and their wrapper source lines. No executable, plugin or compiler was run.

## ABI composition

`data/sources/include/core/Core.ixpl:6–21` sets `coreVersion=2016031002`, includes Akula, and places each following API group immediately after the preceding group's end sentinel. `Akula.ixpl` declares `akulaCoreVersion=2016031000` and invokes the version check from a static block (`702–705`).

| Group | Declared interval | IDs | Interrupt wrapper sites |
| --- | --- | ---: | ---: |
| Akula | 0–248 | 249 | 279 |
| Grid | 249–333 | 85 | 85 |
| Quake world | 334–404 | 71 | 81 |
| MB3 | 405–407 | 3 | 3 |
| Total Core | 0–407 | 408 | 448 |

The extra wrappers are overloads/adapters sharing interrupt IDs. These intervals are fully resolved source expressions and contiguous, not a measured binary dispatch table. All latest Core interrupt sites have an enclosing indexed wrapper; signatures and raw interrupt arguments are retained in the machine report.

`File.ixpl` separately declares IDs 0–24 for create/open/close/size/read/write. These overlap the Core numbers and belong to a separate source interface. Their runtime dispatcher/compilation-context relationship is unverified.

## Contracts exposed by the declarations

| Area | Exposed operations | Evidence and rewrite implication |
| --- | --- | --- |
| Runtime/plugin | Version check, tool registration, load/finalize/view/camera callbacks | `Akula:357–365`; event callbacks are part of the host ABI, not just UI glue |
| Task messages | Five typed buffers and numeric priority | `Akula:369–374`; preserve message boundaries and ordering rules |
| UI/config/resources | Typed config, text I/O, dialogs, translation, font, texture and widgets | Many config settings are deferred; current/next getters differ (`350–355`) |
| Views/camera | Current view/world, cloning/closing, layout, fly/input, projection and camera transforms | View ownership is explicit; do not conflate a world with a viewport |
| Grid | Grid basis/origin/shape, snap settings, visual settings, current cursor/look-at state | `Core.ixpl:11` states these target the current view |
| World | Brush/patch creation, geometry/property/selection operations, undo, persistence and render caching | `Core.ixpl:15` targets the world in the current view |
| MB3 | New world, get/set per-view render settings | Three operations after the world API |
| Process/filesystem | Host call-program and file-dialog services; separate File utility ABI | Original conversion depends on process spawning; native codecs should replace this boundary |

The declarations use `&` for both inputs and returned objects. IXPL reference ownership/lifetime/aliasing is not yet specified; these signatures are not Rust lifetime designs.

### World semantics already explicit in source comments

`Core-QuakeWorld.ixpl:106–171` states that invalid brushes are collapsed/discarded, shown state is independent of selection, several selection operations accept only shown objects not already in a set, and ray queries ignore hidden objects. Inside/touching selection is based on AABBs or brush corners and is not a general exact overlap predicate. Hidden-brush bounds may be stale. An empty selection's bounds are all zero.

The same declarations specify 16-element transform matrices, clone transforms allowing an empty matrix, undo-step/redo clearing boundaries, undo limits that can be zero, spatial-balancing parameter constraints, and render cache levels 0/1/2. These are valuable explicit contracts, but numerical tolerances, topology, failures and actual runtime compliance remain open.

## Task execution and plugin-local services

`Akula.ixpl:369` documents hierarchical task queuing: the first task queued by an executing tool runs next; event-handler tasks are buffered; static blocks cannot queue tasks. This is not enough evidence to model the engine as a simple global FIFO.

Each task carries `int[]`, `long[]`, `float[]`, `double[]`, and `vec3[]`. Client helpers use integer discriminators plus tool IDs/handler indices, sometimes concatenate a string into an integer buffer, and use a named interface tool as an endpoint. Inspecting a task client's source reveals the protocol; executing it still depends on host scheduling and string conversion rules.

`tasks/camera.ixpl`, `grid.ixpl`, and `projections.ixpl` register callback indices and tags. `tasks/raycast.ixpl` keeps one mutable success callback, and `tasks/task priorities.ixpl` keeps one mutable query callback. Concurrent outstanding requests may overwrite these slots; this is a source risk to test, not a reproduced failure.

`getToolID` is documented to return -1 when absent. Task helpers initially use -2 for “not looked up yet” and cache the first lookup. Many do not retry after a missing service. Plugin availability/load timing therefore matters.

## API evolution

| Build | Resolved Core IDs | Maximum ID |
| --- | ---: | ---: |
| 2015-10-03 | 382 | 381 |
| 2015-11-15 | 382 | 381 |
| 2015-11-24 | 388 | 387 |
| 2015-12-08 | 390 | 389 |
| 2016-03-10-c | 408 | 407 |

The November 24 declaration set adds six undo-related names. December changes base-keymap operations. The latest adds property-table APIs, more render controls and additional lifecycle/undo operations. Some older names are replaced, so name additions alone do not explain endpoint-count changes. Group offsets shift; do not reuse current numeric IDs when interpreting older plugins.

Next: P4.03 preconditions/lifetimes/errors/callers for each endpoint; P4.04/P4.05 lifecycle/scheduling experiments; P3.14 host implementations when that investigation is undertaken. The table above closes source enumeration only.