Publish one complete generation¶
A reader should never see half an updated site. This is a publication property. It is separate from parsing and rendering.
The invariant¶
Let \(P\) be the published output tree. During preparation, \(P\) remains unchanged. The next tree \(Q\) is complete before the commit is decided. The commit journal names the output and the records that belong with it.
Preparation can fail. The host abandons the unfinished generation. A decided commit can be interrupted. The next build finishes or restores it from the journal. It does not guess from a staging directory’s name.
Why the cache is outside the output¶
A directory exchange moves everything inside the publication directory. A journal placed inside it would move during the very operation it describes. Its location would cease to be stable when recovery needed it most. Guidedog keeps records in a stable directory outside the publication tree. A custom output uses a sibling cache for this reason.
Durability and visibility¶
Flushing file contents is not the same as flushing directory names.
The algorithm accounts for both before removing the journal.
Platforms differ in how directories are exchanged.
The recovery protocol is designed around those differences.
See lib/project/commit.odin and lib/project/publish.odin for the implementation.
This protects the project publication. It is not a distributed transaction with an external hosting provider. Copying a successful build to a server is another operation, owned by the deployment tool.