How this is published

Everything you are reading was produced by a build you could run. This page describes that build, because a project that argues for reproducible, content-addressed data should be willing to say how its own pages are made.

One line divides the whole repository

On one side, a person writes: papers, site copy, the notes that become reference pages. On the other, programs transform what was written into what you are reading, and nothing on that side makes a judgement about content. The line is not a convention we try to respect — it decides where a file lives. Anything a person's judgement touched is committed source. Anything a program can reproduce from that source is not committed at all, because keeping it would let the copy and the recipe disagree.

The practical consequence is that the published artifacts are disposable. Delete every one of them and a single command rebuilds them byte-for-byte, which is a property the build checks rather than claims: each site is rendered twice and the two trees are hashed against each other, and a difference fails the build rather than being reported.

Three channels, and two of them are not independent

There are three ways out. One renders the sites you are reading now. One assembles the same papers into PDF and HTML documents you can download and keep. The third publishes the posts that make up each domain's feed.

The first two run in sequence rather than in parallel: the site channel reads the document channel's output, because the papers are published here as documents rather than as a second copy in markdown. A reader who meets a paper on this site and a reader who downloads it are meeting the same bytes.

The feed channel is the one that genuinely stands alone. It reads no other channel's output and nothing reads its own, and it does not render anything — a post's body is published as it was written, because the thing that turns it into a page runs at the reader rather than here. What it has instead of a renderer is a gate that refuses, before publication, anything the publisher would refuse on arrival. That check is a restatement of someone else's rules, which means it can fall out of step with them; the rules it restates are named in the source so the two can be compared rather than assumed to agree.

Where the honesty is owed

There is a defect in this we own rather than a design we are pleased with. Of the three channels, only the site channel has the determinism gate described above. The document channel has no equivalent, and its output is an input to the site channel — so the gate that does exist is measuring a build whose inputs it cannot vouch for. The feed channel has no equivalent either; it reports a hash of what it produced, but nothing builds it twice and compares, so reproducibility there is asserted rather than measured. Its isolation limits the damage — it takes no input from the other two — but an unmeasured property is unmeasured whichever channel holds it. These are real gaps, they are ours, and they are not closed.

The build also depends on a scrubbing step that runs over hand-authored intake and not over material pulled in from elsewhere. Nothing is silently trusted there either: what decides whether an outside document belongs on a public page is an explicit list, page by page, and a page naming something that is not on the list fails the build instead of quietly publishing it. We have had that control catch a real mistake, which is the only reason to believe it works.