Document collision, and correct what it made false elsewhere

The new chapter 15 covers the opt-in setup, where resolution runs in the step
and why it runs after the move, shapes and the z-extrusion trap, the asymmetric
masks and the defaults that matter more than the mechanism, tiles as a source
rather than proxies, the response hook and the three ways it is easy to write
wrongly, sensors, the four queries, both partitioners, and what is still not
implemented.

Collision falsified claims in eight other chapters. The physics chapter said
"There is no collision detection, at all" and that collide always raises
AKERR_API; actors had six behaviour hooks; the heap had five pools and four
non-claiming acquires; the status band held five codes; and the design
philosophy had exactly two pluggable subsystems. The appendix gains a
collision.h status section, the three new pool ceilings and a table of the
collision constants that are deliberately not in a public header.

Also fixes chapter labels the renumbering commit left pointing at their old
numbers -- "18. Utilities" linked to 19-utilities.md.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KzBDV2fqgnUAcqCKqKvc71

docs/22-appendix-limits.md

@@ -35,8 +35,8 @@ What the statuses mean is [Chapter 4](04-errors.md).
 | Function | Raises |
 |---|---|
 | `akgl_heap_init`, `akgl_heap_init_actor` | *nothing — no failure path today* |
-| `akgl_heap_next_actor`, `_sprite`, `_spritesheet`, `_character`, `_string` | `AKGL_ERR_HEAP` |
-| `akgl_heap_release_actor`, `_sprite`, `_spritesheet`, `_character`, `_string` | `AKERR_NULLPOINTER` |
+| `akgl_heap_next_actor`, `_sprite`, `_spritesheet`, `_character`, `_string`, `_collision_proxy`, `_collision_cell`, `_bspnode` | `AKGL_ERR_HEAP` |
+| `akgl_heap_release_actor`, `_sprite`, `_spritesheet`, `_character`, `_string`, `_collision_proxy`, `_collision_cell`, `_bspnode` | `AKERR_NULLPOINTER` |
 
 ### `registry.h`
 
@@ -113,7 +113,23 @@ What the statuses mean is [Chapter 4](04-errors.md).
 | `akgl_physics_simulate` | `AKERR_NULLPOINTER`; handles `AKGL_ERR_LOGICINTERRUPT` (H) |
 | `akgl_physics_null_gravity`, `_collide`, `_move` | `AKERR_NULLPOINTER` |
 | `akgl_physics_arcade_gravity`, `_move` | `AKERR_NULLPOINTER` |
-| `akgl_physics_arcade_collide` | `AKERR_NULLPOINTER`, **`AKERR_API` — not implemented** |
+| `akgl_physics_arcade_collide` | `AKERR_NULLPOINTER`, plus `akgl_collision_resolve`'s. A no-op when `self->collision` is `NULL` |
+
+### `collision.h`
+
+| Function | Raises |
+|---|---|
+| `akgl_collision_shape_box`, `_shape_circle`, `_shape_capsule`, `_shape_bounds`, `_shape_interacts` | `AKERR_NULLPOINTER` |
+| `akgl_collision_world_init` | `AKERR_NULLPOINTER`, **`AKERR_VALUE` for a non-positive cell size**, plus `akgl_partitioner_factory`'s |
+| `akgl_collision_bind_tilemap` | `AKERR_NULLPOINTER`, plus `akgl_get_json_properties_boolean`'s; handles `AKERR_KEY` (H) for a layer with no `collidable` property |
+| `akgl_collision_test` | `AKERR_NULLPOINTER`, **`AKGL_ERR_COLLISION` when the ccd arena is exhausted** — the message carries the high-water mark |
+| `akgl_collision_resolve` | `AKERR_NULLPOINTER`, plus `akgl_collision_test`'s and the actor's own `collidefunc`'s |
+| `akgl_collision_settle` | `AKERR_NULLPOINTER`, **`AKERR_VALUE` when the shape is not clear within `maxsteps`** |
+| `akgl_collision_solid_at`, `_box_blocked`, `_query_box`, `_substeps`, `_sync_actors` | `AKERR_NULLPOINTER` |
+| `akgl_collision_proxy_initialize`, `_proxy_sync`, `_cell_initialize` | `AKERR_NULLPOINTER` |
+| `akgl_partitioner_factory` | `AKERR_NULLPOINTER`, **`AKERR_KEY` for an unknown partitioner name** |
+| `akgl_partitioner_init_grid`, `_init_bsp` | `AKERR_NULLPOINTER`. The BSP's `insert` raises `AKGL_ERR_HEAP` past `AKGL_MAX_HEAP_COLLISION_PROXY` proxies |
+| `akgl_actor_collide_block` | `AKERR_NULLPOINTER` |
 
 ### `renderer.h`
 
@@ -180,8 +196,8 @@ What the statuses mean is [Chapter 4](04-errors.md).
 
 ## B. Compile-time limits
 
-Everything below is fixed when the library is compiled. **Only the `AKGL_MAX_HEAP_*` five
-are overridable**, and even those have to be overridden for the whole build — see
+Everything below is fixed when the library is compiled. **Only the `AKGL_MAX_HEAP_*` eight
+and `AKGL_CCD_ARENA_BYTES` are overridable**, and even those have to be overridden for the whole build — see
 [Chapter 5](05-the-heap.md), "The ceilings are a compile-time ABI constraint". The rest are
 plain `#define`s with no `#ifndef` guard: changing one means editing the header and
 rebuilding libakgl and everything linking it.
@@ -206,8 +222,37 @@ rebuilding libakgl and everything linking it.
 #endif
 ```
 
+```c excerpt=include/akgl/heap.h
+#ifndef AKGL_MAX_HEAP_COLLISION_PROXY
+#define AKGL_MAX_HEAP_COLLISION_PROXY          (AKGL_MAX_HEAP_ACTOR * 2)
+#endif
+```
+
+```c excerpt=include/akgl/heap.h
+#ifndef AKGL_MAX_HEAP_BSPNODE
+#define AKGL_MAX_HEAP_BSPNODE                  (AKGL_MAX_HEAP_COLLISION_PROXY)
+#endif
+#ifndef AKGL_MAX_HEAP_COLLISION_CELL
+#define AKGL_MAX_HEAP_COLLISION_CELL           (AKGL_MAX_HEAP_COLLISION_PROXY * 16)
+#endif
+```
+
 Exceeding any of them is `AKGL_ERR_HEAP`.
 
+### Collision
+
+Three of these are not in a public header, because nothing outside the broad phase may size
+anything against them:
+
+| Constant | Value | Where | Bounds |
+|---|---:|---|---|
+| `AKGL_CCD_ARENA_BYTES` | 65536 | `collision_arena.h` | The narrowphase's whole allocation budget. Overridable. One GJK/EPA box pair measures 7,264 bytes |
+| `AKGL_COLLISION_GRID_COLS` / `_ROWS` | 128 | `src/collision_grid.c` | The dense cell-head array, 32 KB. A map wider than 128 cells wraps rather than growing |
+| `AKGL_COLLISION_GRID_MAX_SPAN` | 16 | `src/collision_grid.c` | Cells one proxy may occupy. Anything larger spills to one oversized chain, which is what makes `AKGL_MAX_HEAP_COLLISION_CELL` provable rather than hopeful |
+| `AKGL_COLLISION_MAX_SUBSTEPS` | 8 | `src/collision.c` | Sub-steps per actor per step, and therefore the speed above which tunnelling returns |
+| `AKGL_COLLISION_MAX_ITERATIONS` | 100 | `src/collision.c` | `ccd_t.max_iterations`. libccd's own default is `(unsigned long)-1` — an unbounded loop inside a frame |
+| `AKGL_COLLISION_DEPTH_RATIO` | 2.0 | `collision.h` | The z extrusion, as a multiple of the largest planar half-extent. See [Chapter 15](15-collision.md) before changing it |
+
 ### Strings
 
 `AKGL_MAX_STRING_LENGTH` is `PATH_MAX`, which is 4096 on Linux. That is the capacity of