Choose one subsystem and own it

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

CNA has 22 framework modules, 21 renderer families, 7 platform backends and 4 audio implementations, so a maintainer cannot own all of it at once. This page gives a procedure for choosing one subsystem and becoming the person who can answer for it, with a check that can fail at every step. It covers how to choose from CNA's own numbers, which subsystems are good first choices and why, the dossier to build, a seven-rung ownership ladder with a concrete proof at each rung, and the checks that move work from an AI assistant to the human who signs the change.

Selection criteria

Pick on evidence, not on interest. The criteria below are all answerable from pages and files that already exist; the third column says where.

1. List two or three candidates and fill one row of the table below for each.
2. Find each in the blast-radius matrix and copy its consumer set and minimum cross-check.
3. Answer its readiness questions on paper. Any answer that needs the source is a reading assignment, not a reason to reject.
4. Reject a candidate whose host requirement you cannot meet this month, or that carries more than one risk class.
5. Commit to one for a fixed period. A second subsystem starts only after rung 5 on the first.

Suggested first subsystems, with reasons

Size is headers, sources and test files from the module index, then lines in include/ and src/ (comments included) and test definitions found by a scan of tests/. Renderer families keep tests as example programs, so their definition counts understate them.

Poor first choices, with numbers

These are not unimportant; they cannot be traced in one pass. c-api has 178,863 lines in include/ and src/, 61 headers and its own test executables, and no CI job builds it. content has 60,962 lines and 1,871 test definitions. graphics has 63,571 lines and 2,906 test definitions. platform as a whole has 63,653 lines across seven backends. audio has 17,975 lines and callback threads. A native backend such as Win32 or Wayland needs its own host to prove anything (Win32, Wayland). Start with a candidate above, and use one of these as the second subsystem once the ladder has worked.

The subsystem dossier

The dossier is one working file per subsystem, kept outside the repository and dated to a snapshot. It is the artifact every later rung is checked against. Fill it in the order below; an item that reads “none” or “unknown” is a valid entry, and an empty one is not.

SUBSYSTEM DOSSIER: <module or family>     snapshot: <sha>     owner: <name>
 1 Contract     public headers; XNA or CNAEXT; C route file (CnaCApi*.cpp) or "none"
 2 Trace        public call -> runtime -> backend or host, as function names
 3 Selection    factory, registry or option that makes this implementation live
 4 CMake        target, link edges (PUBLIC/PRIVATE), umbrella member?, gating option, globs
 5 Lifetime     owner / borrower / registry / cache / ambient, drawn as a graph
 6 Generated    generated inputs and outputs, or "none"
 7 Tests        focused target, CTest names, probes, CI cell, skips (77, GTEST_SKIP)
 8 Siblings     another implementation of the same contract, and what differs
 9 Oracle       XNA reference data or "none": what it does and does not prove
10 Reach        C ABI routes, bindings, blast-radius row
11 Unknowns     what could not be established, and the test that would settle it

The table shows what each item asks and fills it in for storage, the candidate with a destructive call. Storage's own page is Storage internals.

The ownership ladder

Each rung has a deliverable and a proof. The proof is a check that can fail, and a failed proof sends you back one rung; time spent is not evidence. Rungs 1 to 3 match the first two stages of First 10, 50 and 100 hours; rungs 4 to 6 use the method in How to understand code you did not write and the rehearsals in Worked human changes.

Rung 3 in commands

The presets are the ones on the curriculum page; the focused target names come from the group table in UnitTests.cmake. Focused executables are built on request and are not registered with CTest, so run them directly from the repository root, which is the working directory CTest gives the discovered cases.

cmake --preset unit                                   # STUB renderer, tests on, examples off
cmake --build cmake-build-unit --target CnaStorageTests
XDG_DATA_HOME=/path/to/disposable ./cmake-build-unit/CnaStorageTests --gtest_list_tests
ctest --test-dir cmake-build-unit -N                  # the whole configuration's inventory
cmake --build --preset unit-math                      # math instead: builds CnaMathTests

Checks that replace AI dependence

An assistant is useful for finding files and for drafting; it is not a source of ownership, because ownership is a claim about consequences that only a person can be held to. The aim is not to stop using one. It is to make every use pass through a step that a person performs and can be checked on. Run these at each rung, and keep the results in the dossier.

The pass thresholds are proposals to adjust for the size of the subsystem, not CNA policy. Which uses stay open changes with the rung. At rungs 1 and 2 an assistant may list candidate files, but every conclusion must come from files you opened. At rungs 3 and 4 it may draft tests, and you write the prediction before it runs. At rung 5 it may propose a patch, but you write the invariant and the predicted effects first. At rungs 6 and 7 no summary substitutes for reading: the review memo and the correction to the pages are yours.

Worked example: the first four rungs on math

Math has no host requirement and no destructive call, so the rungs can be rehearsed without care for side effects. Rung 1. Read math/CMakeLists.txt, then Matrix.hpp, Matrix.cpp and MatrixTests.cpp; the closed-book listing is the 17 source files and what each type owns. Rung 2. Trace Matrix::Multiply and one consumer outside math. The matrix row says a change here can alter rendering silently, so also record where the value structures cross into the C ABI (CnaCApiMatrix.cpp). Rung 3. Build CnaMathTests, write down the expected number of discovered tests before --gtest_list_tests, then read the header of MatrixOracleTests.cpp. It records that XNA accumulates dot products wider than float and narrows once, and that a float accumulation disagreed with XNA in entries a rotation leaves near zero; explain in your own words why the disagreement shows up only there. Rung 4. On a scratch branch negate the sine term in Matrix::CreateRotationZ, predict whether the failures stay inside CnaMathTests or also reach CnaGraphicsTests, run both, and record the difference as the first row of the mutation table. A characterization test needs no CMake edit: the test glob in UnitTests.cmake picks up a new file under modules/math/tests/ at the next build, because the glob is CONFIGURE_DEPENDS.

Scope, exit and handover

• Scope guard. Owning a subsystem includes its tests, its CMake, its C route file if it has one, and the Development page that describes it. It does not include a backend you have not read, and a patch that leaves the module changes the blast radius; return to the matrix first.
• Uncertainty is part of the deliverable. Record what the tests do not prove, using the register in Known uncertainty and history. Renderer-specific and host-specific behaviour stays unproven until run on that host.
• Review of AI-written areas. The method for large generated changes is on Review large AI-generated areas without trusting them; oracle-backed claims are covered on Using the XNA oracle as evidence.
• Handover. The dossier, the mutation table and the last review memo are what a successor reads first. If they cannot rebuild your understanding, rung 7 is not done.
• Re-pin. Before trusting a dossier for a new patch, compare your branch with the snapshot and re-audit every changed path it depends on (how these pages are pinned).