Engineering Post: Locking the public surface before writing a single feature

Before implementing v1.0, I spent time designing its API and architecture and
captured the result in a single design document. I then split implementation into
stages so I could test one group of ideas at a time: M0 for the repository
scaffold, M1 for determinism, followed by metadata, inference, compilation, and
runtime.

M0 tested the first architectural claim: the public API should be deliberate,
and the build should enforce that boundary before the first feature exists.

The layout

I wanted each kind of verification to have a clear home, so the initial solution
contains six projects:

src/Munchausen/                    the single v1.0 package
tests/Munchausen.Tests/            subsystem unit tests
tests/Munchausen.AcceptanceTests/  compiled API scenarios
tests/Munchausen.DeterminismTests/ PRNG vectors + golden outputs
tests/Munchausen.Benchmarks/       BenchmarkDotNet
tests/Munchausen.TestModels/       models shared by every test project

A Directory.Build.props keeps the shared assumptions visible in one place:
net8.0, <Nullable>enable</Nullable>, and <TreatWarningsAsErrors>. The
library project also enables <GenerateDocumentationFile>, which activates
CS1591 warnings. With warnings treated as errors, a missing XML comment on a
public member breaks the build. Nullability and documentation therefore become
API-design decisions, not cleanup for later.

The surface as an executable contract

The most interesting experiment in M0 uses
Microsoft.CodeAnalysis.PublicApiAnalyzers. It tracks two files,
PublicAPI.Shipped.txt and PublicAPI.Unshipped.txt, that together list every
public symbol the assembly exposes. If the code declares a public member that
isn't listed, the analyzer raises RS0016. If a listed member disappears, it
raises RS0017. Because warnings are errors, either change breaks the build.

At M0 both files have zero API entries, only a #nullable enable header.
The surface starts at zero and grows only when I decide a later stage needs a new
public capability. The analyzer turns "remember to review the public API" into a
boundary the build can check.

There's a subtlety worth noting for anyone wiring this up: do not add
<AdditionalFiles Include="PublicAPI.*.txt" /> to the csproj. The analyzer
package already registers matching files; adding them again double-registers
them and quietly breaks dotnet format's ability to auto-populate entries. (I
didn't learn that until a much later milestone, see M7.)

Testing the test

Installing an analyzer and seeing a green build did not tell me much. The current
project had no public members, so there was nothing for it to reject. To learn
whether the boundary worked, I needed to cross it deliberately.

So I committed a canary:

public sealed class Canary
{
    public int Answer => 42;
}

Undocumented and unlisted. The build failed with five useful errors:
RS0016 for the type, its property getter, and its implicit constructor, plus
CS1591 for the two missing XML comments. One canary exercised both guardrails
at once. Then I removed the canary commit and the tree built clean again.

The canary clarified something useful: a green build shows that current code
passes; a deliberate failure demonstrates what the build will protect later.

Shared models

Every test project references Munchausen.TestModels, giving them the same
fixtures: Car/Owner, Customer/Order/Item, a positional record, an
init-only model, and Employee with a self-referential Manager. That last
model records a question the runtime must eventually answer: how should
generation stop when a model contains a cycle?

Verification

dotnet build and dotnet test are green in Release with zero warnings. CI
(.github/workflows/ci.yml) runs restore → build → test on every push and PR to
master. The canary proved the surface and documentation gates; the clean build
confirmed that removing it restored the intended zero-API baseline.

There are still no features to demonstrate, but M0 answered its architectural
question. The repository can now distinguish an intentional public API change
from an accidental one.

What's next: M1, Determinism Core

M1 tests the next design claim: random data can still be reproducible. The
same model and seed should produce the same output on every runtime and OS. Since
.NET does not guarantee that System.Random will preserve its algorithm across
versions, I will build an owned PRNG using SplitMix64 and xoshiro256**.

The central test is simple and unforgiving: output must match published
reference vectors, and a captured golden must reproduce byte-for-byte across
process runs. Like the M0 canary, it turns an architectural intention into
something the build can prove.