# How to verify a generated SDK is reproducible from its spec

> Build one commit twice in empty directories, compare what each would publish by hash, and name the field that varied, so a consumer can rebuild the SDK and check it.

Source: https://voxgig.com/howto/verify-a-generated-sdk-is-reproducible

- Audience: api-producer
- Level: advanced
- Languages: typescript, go
- Verified: 2026-11-21
- Published: 2026-11-21

## Short answer

Pin the generator, the toolchain, and the lockfiles, record them beside the release, and build the commit twice in empty directories. Compare the tarball hashes, and the h1 hash for a Go module. Two sdkgen builds a minute apart gave byte-identical npm tarballs and Go trees, and so did Hey API's client. A mismatch is most often the packaging step: plain `tar` records each file's modification time.

---
## You will need

An SDK generated from an OpenAPI 3 document, Node 22 or later, and GNU `tar` and `gzip`, which
`pack.mjs` runs. The document here is the five-operation Bookshelf API. `record.sh` made the two
builds and ran [`diffoscope`](https://diffoscope.org/) once, and the page's commands read what it
committed under `builds/`, so nothing is generated or downloaded when they run.

## Approaches compared

| Approach | When it fits | What it costs you | When to pick something else |
| --- | --- | --- | --- |
| [`diffoscope` on a mismatch](https://diffoscope.org/) | Two artifacts differ and you need the field that moved | A Python tool whose site advises installing external tools for meaningful results, all in your CI image | The hashes already match |
| [Fern `fern.config.json` and `generatorVersion` pins](https://buildwithfern.com/learn/sdks/current/reference/sdk-config) | Fern generates the SDK and you pin the CLI and every target's generator | Self-hosted generation is an Enterprise feature, so a build on a runner you own needs that plan | You want both builds on runners you own |
| [Hey API exact version pin](https://heyapi.dev/docs/openapi/typescript/get-started) | A TypeScript client from `@hey-api/openapi-ts`, pinned with `-E` | Its `postProcess` tools run from your project, so their versions are inputs too | You need clients in more than TypeScript |
| [npm provenance attestation](https://docs.npmjs.com/generating-provenance-statements/) | You publish from GitHub Actions or GitLab CI/CD and want the source commit on the package | It names the build, but proves nothing about whether a rebuild matches | A consumer wants to rebuild and compare |
| [sdkgen deterministic generation](https://github.com/voxgig/sdkgen/blob/main/docs/explanation/regeneration-overwrite.md) | An sdkgen SDK, where one model feeds a TypeScript and a Go target | Ranges in the generated `ts/package.json`, so the compiler floats until you commit a lockfile | A generator you already run passes the same check |

Voxgig maintains sdkgen, one of the five rows in the table, and this page does not rank it over the other four.

Pins and an attestation record what a build should use, and the two-build hash shows what it
produced. The pins are cheap and come first. `diffoscope` costs an install and earns it on the first mismatch.
Provenance pairs well with all of them, and replaces none.

## Build the same commit twice from empty directories

`record.sh` runs each build in a fresh temporary directory, a minute apart, so the files of the
second build carry other modification times. The generator and the client generator are pinned on the command
line, and `.sdk/package-lock.json`, which the scaffold writes, pins the toolchain behind them.

```bash title="record.sh"
    npx --yes @voxgig/create-sdkgen@0.31.9 bookshelf --def api.json --target ts --target go > scaffold.log 2>&1
    (cd bookshelf-sdk/.sdk && npm ci --no-audit --no-fund > /dev/null 2>&1 && npm run generate > /dev/null 2>&1)
    (cd bookshelf-sdk/ts && npm install --no-audit --no-fund > /dev/null 2>&1 && npm run build > /dev/null 2>&1)
    (cd bookshelf-sdk/ts && npm pack --silent --pack-destination "$dir" > /dev/null)
    npx --yes -p typescript@5.9.3 -p @hey-api/openapi-ts@0.99.0 openapi-ts -i api.json -o heyapi > /dev/null 2>&1
```

Each build also writes the versions it ran and the hash of the toolchain's lockfile. Publish
that file with the release, so a consumer knows what to install before rebuilding.

```json title="builds/a/inputs.json"
{
  "node": "v22.23.5",
  "@voxgig/create-sdkgen": "0.31.9",
  "@voxgig/sdkgen": "4.44.3",
  "@voxgig/apidef": "8.32.4",
  "typescript": "5.9.3",
  "@hey-api/openapi-ts": "0.99.0",
  "sdk package-lock.json sha256": "9ad5433fcffd85d5d3b1afe465fa5d3c35f95d2c3442a85c8236210b102abaf3"
}
```

## Compare what each build would publish

Compare the file you publish, not the tree it came from. `compare.mjs` reads both tarballs entry
by entry, and exits 1 when their bytes differ.

```bash
node compare.mjs builds/a/bookshelf-sdk-0.0.1.npm.tar.gz builds/b/bookshelf-sdk-0.0.1.npm.tar.gz
```

```text output
builds/a/bookshelf-sdk-0.0.1.npm.tar.gz: 210 entries, sha256 e5a8391b2c6d839f5058ab5a82347b34713809d7908009fe1e8382468b0929b7
builds/b/bookshelf-sdk-0.0.1.npm.tar.gz: 210 entries, sha256 e5a8391b2c6d839f5058ab5a82347b34713809d7908009fe1e8382468b0929b7
same bytes: yes
```

A minute apart, the two tarballs are the same 210 entries and the same hash. sdkgen's
documentation says that generating again from the same model gives byte-stable output, and this
run bears it out for the packaged artifact as well as the tree.

A Go module has no tarball to compare. Consumers check it against the h1 hash in `go.sum`, which
[`dirhash`](https://pkg.go.dev/golang.org/x/mod/sumdb/dirhash) computes from filenames and
contents only, so no `mtime` or owner goes in. `manifests.mjs` computes it from each build's
manifest and checks it against the hash Go's own package wrote.

```bash
node manifests.mjs
```

```text output
heyapi.sha256  build a 16 files, build b 16, identical 16, in one only 0
go.sha256      build a 82 files, build b 82, identical 82, in one only 0
go module, build a: h1:hEJScSR0hl95/qOl8neHqoWnL+hGZ5RwepxaXu6aSx8=, the same as Go's dirhash wrote: yes
go module, build b: h1:hEJScSR0hl95/qOl8neHqoWnL+hGZ5RwepxaXu6aSx8=, the same as Go's dirhash wrote: yes
```

## Find what varied when the hashes differ

The generator is rarely the cause. The 16 files of the Hey API client, with a `package.json`
beside them and checked out twice an hour apart, give three different results depending on how
they are packed.

```bash
node pack.mjs
```

```text output
the same Hey API client, checked out twice an hour apart, packed three ways
  tar -czf, as it comes         differ: mtime in 20 entries
  tar normalized, then gzip -n  same bytes
  npm pack                      same bytes
```

Plain `tar` writes each file's `mtime` into its header, and `diffoscope`, run once by `record.sh`,
shows exactly that:

```text title="builds/diffoscope.txt"
--- client-1.tar.gz
+++ client-2.tar.gz
│   --- client-1.tar
├── +++ client-2.tar
│ ├── file list
│ │ @@ -1,19 +1,19 @@
│ │ -drwxr-xr-x   0 root         (0) root         (0)        0 2026-11-21 10:00:00.000000 client/
```

The fix is the one the [Reproducible Builds archive guide](https://reproducible-builds.org/docs/archives/)
gives: sort the entries, set one `mtime` from
[`SOURCE_DATE_EPOCH`](https://reproducible-builds.org/docs/source-date-epoch/), drop the owner,
and tell `gzip` not to store a name or time.

```js title="pack.mjs"
    const tarball = execFileSync('tar', [
      '--sort=name',
      `--mtime=@${SOURCE_DATE_EPOCH}`,
      '--owner=0',
      '--group=0',
      '--numeric-owner',
      '--format=gnu',
```

`npm pack` needed no fix. npm 10.9.9 dated every entry 1985-10-26 and wrote owner 0, whatever
the files carried.[^1]

## Run the same check on Fern and Hey API

Hey API ran here, twice, and its 16 files matched. Its
[get started page](https://heyapi.dev/docs/openapi/typescript/get-started) asks you to pin an
exact version, because the package is in initial development. Its
[output options](https://heyapi.dev/docs/openapi/typescript/configuration/output) empty the output
folder on every run, and `postProcess` runs tools such as `prettier` or `biome` over it afterwards.
Those commands run whatever version your environment provides, so pin them in the same lockfile.

Fern was not run. Its [`fern generate` reference](https://buildwithfern.com/learn/cli-api-reference/cli-reference/sdk-commands)
generates on Fern's cloud after a login, on a guest session, or with `--local` in Docker or
Podman. In the `sdk-config.yml` format, targets run the newest generator unless you pin one. The
reference calls `targets[].generatorVersion` "the exact generator version used for this target"
in its entry. The
[project structure page](https://buildwithfern.com/learn/sdks/current/overview/project-structure)
says that pinning the CLI version in `fern.config.json` provides deterministic builds. Fern's
[self-hosted versioning page](https://buildwithfern.com/learn/sdks/current/deep-dives/self-hosted-versioning)
shows each generated SDK recording `cliVersion`, `generatorVersion`, and `originGitCommit` in
`.fern/metadata.json`, the inputs file this page writes by hand. The
[self-hosted page](https://buildwithfern.com/learn/sdks/current/deep-dives/self-hosted) marks
`--local` generation as an Enterprise feature.

## Check it worked

The suite checks the two committed builds, packs the client three ways, and tests that the
comparison catches what it should.

```js title="repro.test.mjs"
test('the comparison names a one-byte change in one entry', (t) => {
  const dir = scratch(t)
  for (const n of [1, 2]) {
    mkdirSync(join(dir, `b${n}`, 'client'), { recursive: true })
    writeFileSync(join(dir, `b${n}`, 'client', 'a.ts'), 'export const a = 1\n')
    writeFileSync(join(dir, `b${n}`, 'client', 'b.ts'), `export const b = ${n}\n`)
    STEPS['tar normalized, then gzip -n'](join(dir, `b${n}`, 'client'), join(dir, `out${n}.tar.gz`))
  }
  const d = diffTarballs(readTarball(join(dir, 'out1.tar.gz')), readTarball(join(dir, 'out2.tar.gz')))
  assert.equal(d.same, false)
  assert.deepEqual(d.differ, { sha256: 1 })
})
```

```bash
node --test repro.test.mjs | tail -8
```

```text output
# tests 9
# suites 0
# pass 9
# fail 0
# cancelled 0
# skipped 0
# todo 0
# duration_ms 1316.255845
```

## When it goes wrong

The hashes differ even though every file's content matches. The archive carries modification times, an owner, or
directory order. Run `compare.mjs`, or `diffoscope`, to name the field, then fix the packaging
step, not the generator.

A rebuild months later differs where a rebuild the next minute did not. The generated
`ts/package.json` asks for `typescript` `^5.9.3`, and the generator writes no lockfile for it.
Commit the `package-lock.json` the first `npm install` writes, and build with `npm ci`.

The release is signed, but a rebuild still differs. A signature or a provenance statement says
who built the file and from which commit. It does not say that the file is what the commit
builds, which is the question the two-build check answers.[^2]

## When not to do this

Do not stop at two runs on one machine. They share a kernel, a filesystem, and a host name,
so a difference in any of the three cannot show. Put the second build on another runner image before you
promise consumers a match.

Reproducibility alone is no reason to move to sdkgen. Hey API passed the same check on its TypeScript
client with one pin, and it is the smaller adoption for a TypeScript-only SDK. Fern records its
inputs in `.fern/metadata.json` without a script of yours, which suits a team that already
generates on Fern's cloud.

Do not carry this result over to an SDK a coding agent writes. The two builds here are two runs
of fixed generators, and this page measured no agent run. Run the same comparison on two agent
runs from one prompt before you publish either.

## Related how-tos

- [Generate an SBOM for a generated SDK](/howto/generate-an-sbom-for-a-generated-sdk)

- [Check whether two generator runs produce identical output](/howto/check-two-generator-runs-are-identical)

- [Block a release when generated SDK files have drifted](/howto/block-a-release-when-generated-sdk-files-drift)

- [Measure drift between two AI-written clients](/howto/measure-drift-between-two-ai-written-clients)

- [Generate an SDK with Fern from generators.yml](/howto/generate-an-sdk-with-fern)

## Last verified

Verified 2026-11-21 against Node 22.23.5, npm 10.9.9, `@voxgig/create-sdkgen` 0.31.9,
`@voxgig/sdkgen` 4.44.3, `@hey-api/openapi-ts` 0.99.0, `golang.org/x/mod` v0.30.0, GNU tar 1.35,
and Go 1.24.7. Every output block is what the command preceding it printed. Both builds ran in
one sandbox, one minute apart. `diffoscope` 339 ran once, inside `record.sh`, so the commands on
the page do without it. Fern's part comes from its `sdk-config.yml` reference, its `fern generate`
reference, and its project structure and self-hosting pages, read but not run.

[^1]: The date is set in `pacote`, the library npm packs with. Its
[source](https://github.com/npm/pacote/blob/main/lib/util/tar-create-options.js) gives every entry
1985-10-26T08:15:00Z. The comment beside it asks for a date in the 1980s because zip "is confounded
by files dated at the Unix epoch 0" otherwise. The same options force `gzip` level 9, which, the comment says, seems to avoid some
platform-specific optimizations that cause integrity mismatch errors.

[^2]: npm's [provenance page](https://docs.npmjs.com/generating-provenance-statements/) says a
provenance statement lets you publicly establish where a package was built and who published it.
Both are facts about the publishing run, while a consumer who rebuilds is asking about the bytes.