[seanhodges]

Why

convert reads a machine's own program file back into BASIC and answers with the machine it read it as — beside the source, never in it. That is right for a caller writing the text to a file it has just named, and wrong for every caller that hands the text on to something which will have to ask the question again.

An editor opening a freshly converted program has a listing whose machine has just been established beyond doubt and no way to tell, so it falls back on whatever it was configured for, and reports a .prg against a ZX81. The listing already has a way to say this — #MACHINE, one physical line that costs no bytes and beats every other way of settling the question. Nothing stops a caller writing that line itself, and every caller that does is a second opinion about a machine the toolchain had already identified.

What changes

convert can be asked to declare the machine it read. When asked, the source it answers with opens with a #MACHINE line naming that machine, so the text alone is enough to reopen, check, build or run the program as what it is. The command line gains the matching flag.

Off by default. convert's source goes to standard output when no output path is given, and a caller piping that into something else would find an extra first line appear under it. So the declaration is asked for, and the default answer stays byte-for-byte what it is today.

The writing half goes in src/dialects/machineDirective.ts, which already owns recognising, parsing and stripping the directive, imports nothing but a type, and knows about no dialect and no registry. It has no writing half today. Building the line anywhere else would put the two halves of one syntax in two places, and the first divergence would be silent: a line convert wrote that readMachineDirective does not read back.

No route is added or removed, so src/ops/parity.ts is untouched and no caller gains or loses an exemption. No impact on the Dialect / MachineEmulator seam — the operation already knows the dialect it resolved, and the id it declares is the one it resolved to.

One fact worth a test

A #MACHINE line is stripped before a listing is tokenized, so no directive can survive into a machine's binary and come back out of a detokenizer. The recovered source therefore never already carries one, and the prepend never has to look for an existing line. That is a property of the whole pipeline rather than of either end, which is why the tasks pin it with a test rather than a comment.

Who this is for

The agent and the command line as much as an editor: any caller that converts a file and then does anything else with the text would otherwise have to carry the machine alongside it. The immediate consumer is the VS Code client's import command — seanhodges/basically-editor-extensions, import-a-machine-file-as-a-listing — which opens the recovered listing in an editor where nothing else can answer the question. That change rests on this one and says so.

Not done

This is the proposal only — no implementation, no tests run beyond openspec validate. openspec/changes/declare-the-machine-in-a-converted-program/ holds the proposal, design, spec delta and tasks; every task is unchecked.

Spec

Delta on headless-cli, the requirement A machine's binary program file can be read back as BASIC, which gains the option of a reading that says in the source itself which machine it was read as — and the guarantee that a caller who does not ask gets exactly what it gets today. openspec validate passes on the change, and validate --specs on all 22 baseline specs.

🤖 Generated with Claude Code

https://claude.ai/code/session_01NmQqDmxr5ULCtbGmzT3tYc

---

Generated by Claude Code