docs: the tutorial, zero to every feature (#447)

[gafferongames]

docs/TUTORIAL.md: fourteen parts, from an empty directory to a program that uses every feature the C++ reference implements. The narrative path through the material USAGE.md presents feature by feature, linked from the README hub above it.

Scope, and the commit the outputs come from

Every command, output, id, header excerpt and byte count on this page was produced by bin/schema built from bafdb69 (schema v2.4.0-148-gbafdb69), with the serialize siblings at the tags this build pins: serialize v1.16.2 and serialize.c v1.9.2. Every C++ and C program on the page was compiled and run, one at a time.

Re-verified unchanged at 64325e1, this branch's base: every protocol id the page prints, the build version, the baseline projection version and Part 6's byte counts all reproduce. #530, #531, #532 and #534 moved the spec and the certification legs, not the emitted bytes.

The tutorial's scope is the feature set the C++ reference implements at that commit. A specification page without an implementation is not taught, because a reader who follows the page must be able to run it. Three features are in the spec at bafdb69 and refused by the compiler, so they are parts this page owes their implementation PRs:

owed part	what the compiler says at bafdb69
wstring(N), the wide string type (#510)	Bad.schema:3:19: expected newline after field, found "("
field-level tags and doc columns (#529)	Bad.schema:3:21: unknown attribution "tags" — the vocabulary is typed and closed per compiler version (SPEC §4.2)
retain-unknown (#527)	Bad.schema:3:9: a table declaration takes no qualification (docs/SPEC-TABLES.md)

When each lands, it gets its section, run the same way as everything else.

One unit, cumulative

The page grows one schema unit, starlight, from four constants to nine files, and every name it uses is declared in the part that introduces it. Every pasted output belongs to that unit as it stands at that point, and Part 1 says so once and names schema id and schema projection as the way a reader compares.

file	joins in
Game.schema	1 (constants), 2 (enums, flags), 3 (ShipState), 4 (Vector3, the grown ShipState)
Vectors.schema	4, the cpp_native mapping and game_vector2.h
Net.schema	5, Contact through Packet and PacketHeader
Config.schema	6 (ShipConfig), 7 (GunnerSettings, WeaponConfig, GameConfig, optionals, the keyed array), 10 (systems)
Scene.schema	8, Waypoint and Route
Render.schema	12, RenderShip, RenderLaser, RenderFrame

A second unit, starlight/tools, holds the C++-only table forms, introduced in Part 7 by the refusal that prescribes exactly that move (... or move the union and its tables to their own unit). It holds: a union a table closure holds, with a table arm, a scalar arm and a payload-free arm (ToolBody); an array of unions (ToolLog); *string and *bytes (Attachment, AttachmentSet); and Part 8's maps (Fleet). Because they live there, the starlight unit generates for all nine targets, which the page shows in Parts 6, 7, 8 and 12, and Parts 12 and 13 run.

Ruling 1: present state

The rule now lands in Part 6, where tables first appear and the promise is made: the table wire is C++'s within one build, the other eight targets are named with their issues #511 to #518, and the packet wire, the cook and the block cross all nine.

Part 13 is present state. It runs the three crossings that work, each from the starlight unit into C: the packet wire (C reads a ShipState C++ wrote), the cook (C opens Game.cook C++ cooked), and the block (Part 12's produce.cpp to consume.c). No failed handoff as a centerpiece, no rewrite narrative, and no in-flight vocabulary in the page's own voice. Where a refusal appears it is quoted as the tool's own text.

Prerequisites, and programs that build

Part 1 states the Go requirement, the clone, make, the PATH step, and both sibling checkouts with their tags, before Part 3 and Part 13 need them.

Every ./program the page runs is a program the page shows, with its compile line, and every file it reads is created on the page first: ship.bin, forged.bin, dart.bin, config.bin, packed.bin, frame.block, packet.bin, Game.cook and Mine.cook.

Notable corrections from the cold read

• The Vec2/Vec3/GameVec2 muddle is one Vector2 in Vectors.schema with game_vector2.h shown in full and exercised by the program.
• TableReport is shown and printed with all six members after tables: the id-table wire (#435) #507, duplicate included.
• The truncation claim is demonstrated at three cut points, and the form-byte refusal has a forged.bin the page writes.
• The check notice is explained in Part 6 with this unit's output and its exit status, answered in Part 10, and reconciled with "silent on success" in Part 14.
• The retired [<= N] sentence is gone; the [2..8] count hazard is shown through the generated write instead of asserted.
• The "a forged wire with a reference loop is refused" claim is removed, because it is not true. Part 8 replaces it with an exhaustive single-bit sweep of an 80-byte pointered wire and tells the reader to bound their own walks. See below.

Findings

#521 carries every finding, in #447's six categories, with a reproduction command each.

G-19 is the one worth reading first. A single flipped bit in an 80-byte pointered wire loads with an all-zero report (malformed=0, refused=0, unknown=0) and hands the caller a node whose next points at itself. The obvious walk over it never terminates. The sweep is on the page and in the issue.

Also new in this pass: the table wire not crossing languages (G-15) and the refusal verdict living only in C++ (G-16), both the ports work #507 declared; two refusals still describing the wire as "field-tagged TLV" (G-17); and #447's F-16 re-observed now that the local and UTC dates disagree (G-18).

🤖 Generated with Claude Code

[gafferongames]

Rulings from the cold read, under the owner's word of 2026-09-04:

1. The tutorial ships as a present-state page before the table ports land. The rule that the table wire is C++'s within one build today, with the other eight targets refusing a table unit by name behind Go: the table wire's id-table form (#435) #511 to Rust: the table wire's id-table form (#435) #518 while the packet wire, the cook and the block cross all nine, is stated in part 6 where the promise is made; part 13 is present state with no rewrite narrative.
2. The tutorial's scope is the feature set the C++ reference implements at the commit its outputs come from, named in this PR's body. Pages without implementations (doc comments and tags, retain-unknown, wstring) are not taught until they land; each lands its own part with its implementation PR.

Structural fixes from the read land on this branch before it leaves draft: one cumulative unit with every name declared where introduced; the C++-only table forms in a second unit named as such in part 7; the sibling checkouts stated with tags; every program and file shown before it is used; the foreign-unit outputs replaced.