A teammate tries a guide edit that hides authors from agents, regenerates, and commits only
go-mcp/. The OpenAPI document never changed, so the spec checksum in CI still matches. The
release then ships a TypeScript SDK and a Go CLI that know author beside an MCP server whose
tools refuse it.
What you get
You will end up with a release check that reads the entity list out of each generated surface and fails when one disagrees with the committed model. This is for you if one project generates an SDK, a CLI and an MCP server for agents, and they ship together.
Short answer
Record the spec hash each surface was generated from, and also read the entity list each
generated surface carries and compare it with the committed model. A spec checksum catches a
surface built from an older spec, but passes one rebuilt after a local model edit. sdkgen’s
doctor exits 0 on both, check-drift fails both, and Hey API and openapi-typescript need a
header stamp or --check.
You will need
Node 22 or later, Go 1.24 or later to build the MCP server, and a project that generates more than
one surface. Verified 2026-11-21 against Node 22.23.5, Go 1.24.7, @voxgig/create-sdkgen 0.31.9,
@voxgig/sdkgen 4.44.3, @voxgig/apidef 8.32.4, @hey-api/openapi-ts 0.99.0 and
openapi-typescript 7.13.0. The sample holds a Bookshelf document in two versions: api-v1.json
with books, and api-v2.json, which adds /authors.
Approaches compared
| Approach | When it fits | What it costs you | When to pick something else |
|---|---|---|---|
| A checksum recorded in CI artifacts | Any generator, with each surface built by its own job | It sees the spec alone, so a model or guide edit passes, and it names no cause | The generator reads files beside the spec |
| Hey API output header stamp | A Hey API client, where output.header writes a line into every file | A stamp you design and a script you keep, and it records only what you hash | The spec is the only input, and openapi-typescript is already in use |
| openapi-typescript —check | Types from openapi-typescript, checked against the spec in CI | Covers its own output alone, and answers yes or no with no reason | Several generators feed one release |
| sdkgen check-drift | An sdkgen project, before a release | Deletes and regenerates every target, and needs the .sdk toolchain installed | You need a check that runs in seconds on every push |
| voxgig-sdkgen doctor | Checking the .sdk copies against the scaffold | It never reads generated output, so it passed every release here | The question is which model a surface came from |
Voxgig maintains sdkgen. This page compares two of its commands with a checksum and the checks of two other generators, and sdkgen is not the recommendation.
The checksum works for every generator and says nothing about why a surface differs. The two
generator-aware rows know their own output: openapi-typescript compares its types, and
check-drift compares every sdkgen target. Neither looks across tools, so the model check below
reads the surfaces directly.
Build three releases from one project
generate.sh scaffolds one project from api-v2.json with four targets and commits it as
release:
cp "$here/api-v2.json" api.json
npx --yes @voxgig/create-sdkgen@0.31.9 bookshelf --def api.json --target ts --target go --target go-cli --target go-mcp > scaffold.log 2>&1
(cd bookshelf-sdk/.sdk && npm run generate > ../../generate.log 2>&1)
Two copies of it then regenerate every target, and the script puts back only their
go-mcp/tools.go.
old-spec swaps in api-v1.json first. model-only appends guide-edit.aontu, which switches
the author entity off, and leaves that edit out of the commit. For each surface the script
writes the artifact its CI job would: the sha256 of the spec it generated from.
No surface carries a version on its own. The model holds main.kit.info.version, 1.1.0, but a
search of ts/, go/, go-cli/ and go-mcp/ found that version and the spec’s hash in no file.
A check therefore has to read the surfaces themselves.
Run four checks on each release
verify.mjs runs the checksum and the model check on each release and reads the doctor and
check-drift runs that generate.sh recorded:
node verify.mjs
release doctor spec checksum surfaces vs model check-drift
release exit 0 ok ok exit 0
old-spec exit 0 FAIL go-mcp FAIL go-mcp exit 1 go-mcp/tools.go
model-only exit 0 ok FAIL go-mcp exit 1 go-mcp/tools.go
The checksum caught the older spec and passed the model edit, which is the pitfall in one row.
doctor passed all three, because it compares the copies under .sdk/ with the scaffold and
never opens go-mcp/. check-drift failed both bad releases and named the file.
@voxgig/sdkgen 4.45.0 with @voxgig/apidef 8.33.1 gave the same doctor and check-drift
results on all three releases.
Read the entity list out of each surface
checks.mjs reads three files: the entity block in the SDK’s ts/src/Config.ts, the
case lines in go-cli/words.go, and the enum each tool in go-mcp/tools.go passes to
entitySchema. A reader that finds nothing throws, so a changed template fails the check
instead of passing it.
'go-mcp': (dir) => {
const lists = [...read(dir, 'go-mcp/tools.go').matchAll(/InputSchema: entitySchema\[\w+\]\(([^)]*)\)/g)]
if (lists.length === 0) throw new Error('no tool schemas in go-mcp/tools.go')
const sets = lists.map((m) => sorted([...m[1].matchAll(/"([a-z0-9_]+)"/g)].map((x) => x[1])).join(' '))
if (new Set(sets).size !== 1) throw new Error(`go-mcp tools disagree with each other: ${sets.join(' | ')}`)
return found(sets[0].split(' ').filter(Boolean), 'go-mcp/tools.go')
},
node verify.mjs generated/model-only
generated/model-only: model has author, book
ts SDK ok author, book
go-cli ok author, book
go-mcp FAIL book
The command exits 1. generate.sh also built each MCP server and sent it tools/list over stdio;
both of its tools answered with an entity enum of book alone, and a test holds the reader to
those answers.1
Stamp the Hey API and openapi-typescript clients
Hey API and openapi-typescript generate from the spec alone, so the spec hash is the whole
question for them. Hey API’s output.header
option takes a function of the default header, and this configuration adds the hash:
export default {
input: spec,
output: {
path: process.env.OUT ?? 'client',
header: (ctx) => [...ctx.defaultValue, `// openapi-sha256: ${sha256}`],
},
}
openapi-typescript needs no stamp: its --check flag regenerates in
memory, compares with the file, and exits 1 when they differ, writing nothing. stamps.mjs runs
both against the release spec, with a client from each document:
node stamps.mjs
release spec api-v2.json, sha256 be941341ba80
Hey API from api-v2.json ok 4 files, be941341ba80
openapi-typescript from api-v2.json ok --check exit 0
Hey API from api-v1.json FAIL stamp 554e49a1d327, spec be941341ba80
openapi-typescript from api-v1.json FAIL --check exit 1
Check it worked
Ten tests cover the table, the readers, the recorded tools/list answers and both stamps:
node --test verify.test.mjs
1..10
# tests 10
# suites 0
# pass 10
# fail 0
# cancelled 0
# skipped 0
# todo 0
Four of them break copies of Config.ts, tools.go, the artifacts and the Hey API files, and
expect each check to throw or fail. One drops the old-spec server into the good release on
purpose, and the model check names go-mcp.
When it goes wrong
doctor reports .sdk matches the scaffold and the MCP server is still wrong. It compares only
the copies target add wrote under .sdk/. Gate the release on check-drift, or on a check that
reads the output.
check-drift reports M go-mcp/tools.go without saying why the file changed. It names the file, not the cause.
The model check names the surface and the missing entity, and the artifact hash says whether the
spec moved.
A release passes the checksum with a surface’s artifact missing. A check that compares only the
artifacts it finds cannot see the one that is absent. checksum() names the surfaces a release
ships, and fails one with no artifact, a hash that is empty or malformed, or a file that names
another surface.
A Hey API file has no stamp. A file written by hand, or by an older configuration, has no header
line. stamps.mjs reads every file under the output, subdirectories included, and fails an
unstamped one rather than skipping it.
When not to do this
Do not rely on a spec checksum alone for a generator that reads anything beside the spec. sdkgen reads the guide and the project overlay, so a model edit leaves the hash unchanged.
Do not run check-drift on every push in a large project. It deletes and regenerates every target,
work the script’s own comment puts at minutes. Run it before a release, and run the
model check on every push.
Do not take doctor’s exit 0 as evidence about generated output. Hey API is the better choice when
the release is one TypeScript client: one header option and a short script cover it.
openapi-typescript’s --check suits a team that ships types only, because it needs no script at all.
Related how-tos
Last verified
Verified 2026-11-21 against Node 22.23.5, Go 1.24.7, @voxgig/create-sdkgen 0.31.9,
@voxgig/sdkgen 4.44.3, @voxgig/apidef 8.32.4, @hey-api/openapi-ts 0.99.0, openapi-typescript
7.13.0 and TypeScript 5.9.3. Every output block is what the command preceding it printed. The
scaffold, the three generations, doctor, check-drift on 4.44.3 and 4.45.0, the MCP server
builds and the Hey API runs happened once, in generate.sh, and their output is committed. The commands here read that
output, and stamps.mjs runs openapi-typescript’s --check live.
Footnotes
-
The enum is plain JSON Schema: the value must be an array, should have at least one element, and its elements should be unique. A server with one entity fewer still satisfies all three, so validating the tool schemas cannot find the gap. ↩︎ Back to text