Rerunning the generator in --check mode makes a stale snapshot fail the build

The generator that writes the catalog also runs in `--check` mode, and it runs whenever any `.go` file, the manifest, the modules file or the snapshot itself changes ^[14]. A `--check` run regenerates the artifact and compares it with the committed one, so a snapshot that no longer matches the code fails the build ^[22]. The generator is installed at the same platform version the service has in its modules ^[15]. Without that pin, the check generates with a different tool and reports differences that belong to the tool.

The arrangement being replaced is three files for one interface: the schema declares the call, a separate OpenAPI document describes the HTTP surface, and human-facing documentation is the third ^[7]. Anton's version keeps one file per interface and treats everything else as output ^[2]. Two of those three artifacts stop being maintained by hand ^[23]. "Nothing in the pipeline notices when the schema gains a field the HTTP document has never heard of," he wrote ^[8].

He started somewhere else. The environment variable descriptions and the metrics descriptions were written by hand in files next to the code, and both drifted. Nothing failed, and the description stayed wrong for as long as nobody read it against the source ^[9][10]. Wrong documentation pages nobody. The catalog now records `defined_in`, the file and the line of the declaration, for a variable declared by the service configuration, and the owning catalog for one declared by the platform ^[12]. The metrics snapshot has one row per metric plus a `<dynamic>` row for the factory that registers metrics at runtime ^[13]. "A description written by hand drifts. A description that is derived and checked does not," Anton wrote ^[17].

The catalog leaves out resource variables. The platform builds their names by concatenation at runtime, so there is nothing static to read ^[16]. Anyone treating the catalog as the complete list of what the service consumes will be short by exactly those names.

For the HTTP half to transfer, the surface you need has to be expressible in the annotation the method carries. The specification is produced from that declaration, and the schema holds the messages, the required fields, the bounds and the refusal codes ^[6][5]. The post is one engineer's account of one system, and it does not report a service count, a team size, or how often the check has fired ^[21]. The compatibility claim is the one I would test before adopting any of it. Anton says the contract build tool checks every change against the published schema, so a breaking change is visible before a line of implementation exists ^[19].

"This is how I do it right now, with the price attached - maybe you already do it better, maybe you see it differently," he wrote ^[20].