Take engineering ownership of CNA

CNA snapshot 009d40f5  ·  Development › Human Takeover  ·  source links pinned to 009d40f5

The Human Takeover pages are a route from an unfamiliar, heavily AI-developed C++ repository to human-authored, human-reviewed maintenance of CNA. They do not teach game application code — the user documentation does that. They teach how to find which part of CNA is responsible for a behaviour, recover its call and ownership paths, decide how far a change can travel, create evidence, and know when a change is safe enough to ship. Read them if you are about to become the person who answers for CNA's source.

The route through the takeover pages

Every stop on the route produces something a reviewer can check without the original author or an AI agent in the room: a diagram, a trace, a failing test, a validation record.

Inherited system → canonical mental model → staged source study
        ↓                     ↓                        ↓
Find owner of behaviour → call/ownership trace → narrow failing test
        ↓                     ↓                        ↓
Smallest patch → cross-backend / C ABI review → configured + live validation
        ↓
A human can explain the change without relying on its author or an AI agent

Read in this order

The core path is the twelve pages below: ten guides and the two historical case studies, placed where they are most useful. The sidebar and the Previous/Next links follow the same sequence and also include three additional stops on this route (own a subsystem, reviewing AI-generated areas, the XNA oracle); they are listed after the table.

1. What a human maintainer inherits — the physical repository, the separately selected platform / audio / renderer, and where small changes have wide effects.
2. The canonical mental model — who starts execution, who owns each object, which abstraction receives a call and which selected implementation acts.
3. First 10, 50 and 100 hours — a staged source-reading route with exercises and a stated outcome per stage.
4. How to understand code you did not write — the twelve source checks and the investigation-record template, applied to three real CNA traces.
5. Worked human changes — five rehearsed changes (runtime, shared graphics, Vulkan, Win32, public API) and one review memo for all of them.
6. Case study: Game component lifetime — a real, fixed lifetime defect reconstructed from Git history (first case study).
7. Case study: storage containment — a real, fixed destructive-boundary defect (second case study; see below).
8. Ownership and lifetime master map — who may still use an object when it dies.
9. Thread and callback map — which code can run while another object is changing.
10. Blast radius and readiness — how far a one-line change can travel, and the readiness questions before editing a subsystem.
11. What to test after changing X — the change→test matrix and how to report evidence honestly.
12. Known uncertainty and history — what the TARGET source and tests do not establish, and which architectural history is recoverable from Git.

The three additional stops in the sidebar are Choose one subsystem and own it (after the mental model), Review large AI-generated areas without trusting them (after the case studies) and Using the XNA oracle as evidence (before the uncertainty register).

The standard for independent maintenance

A developer is not ready to change a subsystem merely because its API is familiar from XNA. They should be able to draw its construction path, normal call path, mutable state, owner and borrowers, failure path, teardown and tests, and name at least one independent backend or host whose behaviour could differ — CNA ships 7 platform implementations, 4 audio implementations and 25 renderer identities over 21 implementation families, and a green run on one of them says nothing about the others. For a public interface they must also locate the consequences in the experimental C ABI (0.29.0 at this snapshot) and in the external language bindings, which target ABI 0.21.x and are separate projects (see the bindings boundary).

The Game component lifetime case study shows this reasoning against real Git history. The deeper runtime, graphics, platform, content and C API internals pages exist to support that reasoning — not to replace it with a catalogue. When you need the "which file do I open" answer for a concrete task, the Maintainer Handbook has one recipe per common change.

Keep a human-readable investigation record

For every nontrivial patch, write a short trace before editing:

• the observed symptom and an exact reproduction;
• the selected CMake axes (CNA_PLATFORM, CNA_AUDIO_PLATFORM, CNA_GRAPHICS_RENDERER / CNA_GRAPHICS_RENDERERS, plus toolchain and CNA_ENABLE_SDL) and, for graphics, the renderer that was actually active at run time;
• the public entry point and the concrete implementation it reaches;
• the owner of each object and its destruction order;
• the source-level invariant the change must preserve;
• the failing test, written before the patch where possible;
• the other implementations of the same contract;
• the validation actually run, including skips (CTest skip code 77, GTEST_SKIP) and configurations not run.

The fill-in template is on the investigation page. The record need not become permanent website prose, but it makes review possible when the author is unavailable. Do not use the generated references as conclusions: they locate declarations, targets and options, while CMake source, the implementation, its call sites and its tests establish behaviour.

Practice a destructive-boundary review

The storage containment case study uses a real historical CNA fix to practise identifying an authorization root, following a shared path helper beyond the subsystem that owns it into content and playlist code, and checking the side effects of the test fixture itself. It is a good second exercise after the Game component lifetime study because it needs a different skill: proving that a proposed path stays confined before an irreversible filesystem operation. The user-facing rules it protects are described under Storage: path containment.

How the takeover pages relate to the rest of the site