Contributing¶

One thing is worth saying before you spend an evening on something: plausible code is not welcome here. 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 and looks right but came from somewhere else is the hardest thing to spot six months later, when it is sitting next to recovered work and looks exactly like it.

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. chikuma/ui/COMPONENTS.md: every UI class, marked recovered, stand-in, or INVENTED
4. chikuma/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, the archive or the firmware already states it somewhere; go and find where.

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. 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 one summary at the end, and say when something you expected turns out not to be true. "I don't know yet" is a fine update. State what is measured, what is inferred, and what is still open.

Hardware safety¶

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