COMTRAN Reconstruction

What is built,
and what is not

Three tracks run at once. The compiler is the mission. The tooling exists to keep the punched decks honest. The website is the page you are on and whatever comes after it.

A finished item carries the day it was finished. An unfinished one carries no date, because the work takes as long as the evidence takes and a date here would be a guess dressed as a plan.

The compiler

Seven steps from a box of cards to a program that runs. The first four are finished, and each one is held to the 1962 manual by a test that compares output byte for byte.

  1. M0 Finished 2 August 2026

    The commitments

    Before any code, the choices that could not be un-chosen: which of the two manuals the compiler follows, that the output is real 7090 machine code, that a deck is stored as holes and not as text, and that correctness means a diff against the listing IBM printed.

    Every decision, with the evidence that forced it

  2. M1 Finished 3 August 2026

    Cards in, listing out

    The deck is split into its divisions, read into statements, and printed as a listing in the page geometry measured off the 1962 scans. The payroll sample comes through with the same statement numbers the 1962 compiler gave it and no complaints.

    How the front end was built

  3. M2 Finished 3 August 2026

    The parser

    Every statement in all three divisions, plus the control cards that drive a compile. When something is wrong, the message is the manual's own, keyed to the statement number, the way the 1962 compiler keyed it.

    How the parser was built

  4. M3 Finished 5 August 2026

    What the names mean

    Levels, pictures and type codes become storage: every name in the program bound to an address and a machine word. The addresses are checked row by row against the ones printed on the 1962 page.

    How storage was worked out

  5. M4 Being built now

    Machine code

    The verbs become 7090 instructions. The assembly model and the storage map are built and print correctly; the verb generators are the work in hand. There is a right answer to check against, because the manual prints this program's assembled object code in full.

    Eighteen of those printed pages have to be read off the scans first, one page at a time, before a single instruction is generated. That reading is most of the work, and what it takes to do it honestly is its own page.

    The code generation design, with every open question

  6. M5 Not started

    Reading and writing

    Files, tapes and printed reports. A payroll program that cannot read a tape or write a report does nothing at all, and this is the runtime that lets it.

  7. M6 Not started

    The acceptance test

    Compile the payroll sample, run it on an emulated 7090, and reproduce the report the 1962 manual prints beside it. Byte for byte, the way the listing already matches. That is the finish line as the project is scoped today.

The tooling

A COMTRAN program is a deck of punched cards, and this project stores one as holes rather than as text. These four exist so that no hole is ever lost to a careless edit.

  1. T1 Finished 3 August 2026

    The deck tool

    Converts a punched deck to readable text and back again, and refuses to let the two drift apart. It runs as a commit hook, as a build check, and as the thing that lets git show a deck in a diff.

  2. T2 Finished 3 August 2026

    The punchcard editor

    An editor for a binary deck inside VS Code: the punch grid, the row the keypunch printed along the top, the column rulers, and click to punch. Saving either half of a deck brings the other half with it.

  3. T3 Finished 3 August 2026

    The deck server

    Deck tools served to an assistant working in this repository, so a card is always changed through the format's own rules and never by hand.

  4. T4 Finished 3 August 2026

    Colouring the fields

    Both deck views colour the card fields from one shared table of column positions, so no two views can disagree about where a field begins.

The website

This site is the door. It exists so that someone can react to the reconstruction without cloning a repository, and so that the limits are in the reader's way rather than in a footnote.

  1. W1 Finished 10 August 2026

    The compiler in your browser

    The front page. The compiler is built to WebAssembly and runs on your machine, with the punched card, the deck, the compiler's own complaints and all six of its stages.

    Your deck comes away with you: download it as the punched card file the rest of this repository reads, or copy a link that carries the whole deck inside the address.

    One item on its own list is still missing: a panel that sets this page's listing beside the 1962 print. The test suite already makes that comparison, byte for byte, before anything is merged.

  2. W2 Not started

    The sources

    Both manuals in full, and each of the 345 page scans beside the text that was read off it. Every claim on this site starts on one of those pages, and this is where you go to check one.

  3. W3 Not started

    The stages

    Pick one statement and follow it through every stage of the compiler at once, joined by the number the 1962 compiler gave that statement.

  4. W4 Not started

    Teach it

    A tutorial that writes a program with you, card by card. A Run button arrives with M5 and M6 and not before, because until then there is nothing to run.

Going deeper

This page is a summary, and it is kept in step with the repository by rule rather than by memory: a milestone that changes state here changes state in the same commit that moved it.

Nothing on this page is a promise. It is a record of what has been done, written down so that a reader can tell the built part from the intended part without having to guess.