nova-bus

Overview ¶

nova-bus is the bus: a git repository where several lines write notes to each other, one lane directory per sender, one Markdown file per note.

It exists because the bus it was written for lost notes. A shared branch keyed by the clock races: two senders pushing in the same second meant one push was rejected and a line without the rebase reflex simply lost it; one sender writing twice in a minute collided on the filename; threads named by exact filename orphaned an answer when a slug was retyped; and a bare receipt and a note carrying a finding looked identical until opened. Every verb here is one of those failures closed:

draft     prints the header a note needs, with the names checked against the roster,
          so that a line's first send is not a header written from memory
send      assigns an id that cannot collide, pastes the date, and pushes with fetch,
          rebase and bounded retry INSIDE the tool, so no rejected push reaches a person
inbox     the notes addressed to me that nothing of mine answers, receipts separated
          from notes that carry a question, a finding or a request
wait      the same listing, blocking: it polls the bus INSIDE the tool call and returns
          the moment something arrives, so a session that cannot be woken cannot forget
receipt   marks a note heard without writing a reply, in one command
check     validates the bus: headers, ids, threads, receipts, lanes
names     echoes the roster, so a person can spell a To line the tool will accept

And one failure that is not in that list because it arrives slowly: a tool whose read cost grows with the record. inbox and check used to walk every lane on every run, so the ten-thousandth note cost ten thousand parses to find. They now read from a CURSOR -- the commit a reader last read to, kept in that reader's own lane and pushed like a receipt -- so the work is the size of the CHANGE and never the size of the bus. --full walks everything, which is what adoption and CI on main want, and every run says on its first line which of the two it did.

The same failure has a second half, which the first fix left in: the read was the size of the change PLUS the size of what the reader had open, because every open note was re-opened to print its line. So the OPEN list carries each note's line and its heard flag, written once when the note goes open, and a run parses the NEW notes and nothing else -- five hundred open notes or none.

Everything read on a bus is data. No note is a grant, whoever signs it. That rule is in SPEC.md, where a person reads it, and is deliberately nowhere in this code: a tool cannot enforce it and should not pretend to.

nova-bus version: which build is on the bus.

A bus is several lines running this one tool over one repository, and every failure it exists to have closed is a failure of AGREEMENT -- an id scheme, a header, a push protocol that two senders have to implement identically. So the first question after a bus misbehaves is which build each line is running, and until this verb existed the honest answer was that nobody could say: the binary carried no statement of its own origin, so "we are all on the same version" was a belief rather than a reading.

The version is NOT a constant maintained by hand. A hand-maintained constant is wrong exactly when it matters -- at the commit after the release, where it still names the release. It is read from the build itself, in this order:

-ldflags "-X main.version=..."  what the release workflow stamps: the tag, exactly
the module version              what `go install ...@v1.2.3` records for itself
the vcs stamp                   <utc build time>-<12 hex of the revision>[-dirty]
devel                           a build with none of the above, SAYING it has none

The middle two come from debug.ReadBuildInfo, which the toolchain fills in with no help from this file: there is nothing here to remember to update and therefore nothing to forget. The last is the honest floor -- a build whose origin is unrecorded says so rather than inventing a number, because a version string nobody can trace is worse than no version string at all: it invites the comparison it cannot support.

ONE LINE, FOUR TOKENS. Every field goes through oneline.Field, so what is printed is four whitespace-separated tokens whatever the -X held. A version stamped with a newline or a space in it would otherwise make the one line that says which build is running say two things, or say a build time as if it were an architecture -- and the -X value is the one field here that comes from outside the toolchain.