Contributing¶

The bar here is unusual, and it is worth stating plainly before you spend an evening on something.

Chikuma does not accept plausible code. Every line that is RetailOS's behaviour has to come from the reverse: the archive's records, the firmware's own code, or a measurement on it. Code that works, looks right, and was not derived from any of those is the thing this project most wants to keep out -- because it is indistinguishable from recovered work six months later.

What a contribution looks like¶

Read, in this order:

1. CLAUDE.md at the repository root -- the method and the working agreement
2. reports/session_state.md -- where the last session stopped
3. retailos_re/ui/COMPONENTS.md -- every UI class, marked recovered, stand-in, or INVENTED
4. retailos_re/ROADMAP.md -- the plan, and what is done with the gate that proves it

Then follow the loop. A finding that has not been through all six steps is not finished.

Three things that will get a change sent back¶

A constant chosen in C. If you are about to pick a value, stop -- the archive or the code already states it. Go and find where. This is the single most common failure mode here and it produced the worst work in the repository.

A stand-in that cites a function nobody opened. Stand-ins are allowed. A stand-in must say it is one, in the file, at the place it stands in, and must name the function that would answer it -- and that function must have been read. make gaps checks this mechanically: it pulls the addresses cited in every stand-in comment and asks the symbol dump what they are called. A citation still reading FUN_xxxxxxxx is a function nobody has ever opened.

A test against a fixture you wrote. Tests run against the real volume image and the real archive blob. A test that passes because the fixture was written to match the parser proves nothing about the device.

Gates¶

Every milestone needs a gate the emulator can check, because a milestone without one cannot be distinguished from a milestone you believe you reached. This project has twice produced confident wrong answers that only a measurement caught.

make verify boots on QEMU, presses buttons, and a fault fails the gate.

Structure¶

Structure follows the firmware, not our taste. If the layering you are adding differs from the image's, yours is wrong. HFS and HFS+ are one driver there, so they are one driver here.

Libraries¶

Use upstream for what Apple used upstream for -- FreeType, SQLite, zlib, Vincent. Match the version and configuration the image shows, and say so in the file. The test is: could this line have been different if Apple had chosen differently? If yes, it must be recovered. If it is an implementation of a public standard that somebody already wrote, take theirs.

Reporting a finding¶

Report each pass as it lands -- hypothesis, evidence, verdict -- rather than a summary at the end. Say when a hypothesis dies; that is a result. "I don't know yet" is a valid update.

State what is measured, what is inferred, and what is still open. A plausible cause is not a cause.

Hardware safety¶

Never write to a mount found by a glob. /Volumes/iPod is somebody's actual device, and this project has already destroyed one library that way. Address volumes by the node the mount returned. Test images go through the repository's own mount tool, which mounts at a path of its own and refuses anything else.