fix: harden stable package payloads

[tonyketcham]

Update GraphQL Code Generator and esbuild to supported releases without changing generated output. Trim Proof's npm payload to its bins and built files.\n\nTest plan: pnpm verify; package audits; Proof pack and CLI smoke checks.

Depends-On: #237

[tonyketcham]

This pull request is part of a Mergify stack:

#	Pull Request	Link
1	release: prepare Flatbread 1.0	#236
2	fix: remove stale release dependencies	#237
3	fix: harden stable package payloads	#238	👈
4	fix: make core declarations portable	#239
5	docs: record upstream release limits	#240
6	chore: move proof to its own repository	#241
7	fix: retarget Cursor agents at external Proof	#242
8	feat: brand agent memory as Proof and the runner as Oven	#244

[tonyketcham]

Revision history

#	Type	Changes	Reason	Date
1	initial	2d66900		2026-08-12 18:16 UTC
2	rebase	2d66900 → a9543f2 (rebase only)		2026-08-12 18:16 UTC

[cursor]

Stale comment

Review verdict

REQUEST_CHANGES — consensus HIGH on the unverified public “byte-identical files” CHANGELOG contract after multi-major @graphql-codegen/* bumps (also two independent HIGHs once CODEGEN_OUTPUT_VERSION / cache invalidation is included).

Chunk-bound feedback

CHANGELOG.md:43-50 — severity: HIGH — flagged-by: dependency-runtime-surface, release-discipline, docs-and-positioning, dx-and-examples

• Risk: The note asserts that the same schema still generates byte-identical files across cli 5→6 / plugin majors and an esbuild 0.15→0.25 pin jump, with no golden checksum, fixture, or example regen in-tree. Major codegen lines document emission changes, and bundling the claim with esbuild invites readers to infer config .mjs byte-stability too.
• Minimal fix: Split into two bullets (codegen vs esbuild); drop “byte-identical” / blanket “nothing changes” unless a committed golden (or example regen) proves it—otherwise say compatible / smoke-tested / semantically equivalent, scoped per surface.

packages/codegen/package.json:37-40 — severity: HIGH — flagged-by: dependency-runtime-surface, dx-and-examples

• Risk: Four @graphql-codegen/* majors ship while Flatbread’s invoke path stays API-compatible, but cache keys still ignore the new generator line (CODEGEN_OUTPUT_VERSION stays at 2; resolved plugin versions are not hashed), so existing .flatbread-codegen-cache.json can skip regen after upgrade.
• Minimal fix: Bump CODEGEN_OUTPUT_VERSION in packages/codegen/src/hash.ts (or hash resolved codegen package versions) in this release; stop asserting byte-identity unless a golden compare proves it.

packages/config/package.json:43-43 — severity: MED — flagged-by: dependency-runtime-surface, dx-and-examples

• Risk: Exact esbuild 0.15.1→0.25.0 is a large 0.x jump on the only consumer; load.test.ts smokes a minimal config, but every flatbread start / codegen path bundles real configs with no assert on those edges.
• Minimal fix: Keep the exact pin; add a load fixture mirroring examples/nextjs/flatbread.config.js.

packages/proof/package.json:38-38 — severity: LOW — flagged-by: release-discipline, docs-and-positioning, dx-and-examples

• Risk: Dropping src/scripts from files is the right publish trim, but files still lists unused root *.d.ts, and published scripts still advertise monorepo paths under unpackaged dirs.
• Minimal fix: Remove the unused *.d.ts entry; drop or relocate monorepo-only script entries from the published manifest.

Coverage plan

1. packages/codegen/src/__tests__/e2e.test.ts — positive — same fixture schema/documents regenerate byte-identical (or explicitly versioned) output vs a committed golden; fail CI if bytes drift without a CODEGEN_OUTPUT_VERSION bump.
2. packages/codegen/src/__tests__/*cache* / hash unit — positive — after simulated @graphql-codegen/* (or CODEGEN_OUTPUT_VERSION) bump, cache miss forces regen.
3. packages/config/src/load.test.ts — edge:nextjs-shaped config — loads a fixture with externalized @flatbread/resolver-svimg, relative imports, and overrides under esbuild 0.25.0.
4. packages/config/src/load.test.ts — edge:.ts config / externalize — if supported, assert transform + externalize still succeeds post-pin.

Reviewer scoreboard

• dependency-runtime-surface: 3 findings, 2 coverage gaps, signal:HIGH
• release-discipline: 3 findings, 1 coverage gaps, signal:HIGH
• docs-and-positioning: 3 findings, 2 coverage gaps, signal:HIGH
• dx-and-examples: 4 findings, 2 coverage gaps, signal:HIGH

Perspectives: dependency-runtime-surface, release-discipline, docs-and-positioning, dx-and-examples (release/docs/deps-only path; no packages/*/src). Models: grok-4.5 high / composer-2.5.

  

_{Sent by Cursor Automation: Flatbread PR Review}

[cursor]

HIGH — “Nothing you get out changes: the same schema still generates byte-identical files” is a falsifiable public contract after multi-major @graphql-codegen/* bumps (and an esbuild 0.15→0.25 pin in the same breath), with no golden checksum, fixture, or example regen in this PR.

Minimal fix: split codegen vs esbuild into two bullets; drop “byte-identical” / blanket “nothing changes” unless a committed golden (or example regen) proves it—otherwise say compatible / smoke-tested / semantically equivalent, scoped per surface.

[cursor]

HIGH — Four @graphql-codegen/* majors ship here, but CODEGEN_OUTPUT_VERSION in packages/codegen/src/hash.ts stays at 2 and resolved generator versions are not hashed. Existing .flatbread-codegen-cache.json can skip regen after upgrade while the CHANGELOG claims identity.

Minimal fix: bump CODEGEN_OUTPUT_VERSION (or hash resolved codegen package versions) in this release; stop asserting byte-identity unless a golden compare proves it.

[cursor]

MED — Exact pin esbuild 0.15.1→0.25.0 is a large 0.x jump on the only consumer. load.test.ts smokes a minimal config, but every flatbread start / codegen path bundles real configs (externalized workspace packages, relative imports, overrides) with no assert on those edges.

Minimal fix: keep the exact pin; add a load fixture mirroring examples/nextjs/flatbread.config.js.

[cursor]

LOW — Dropping src/scripts from files is the right publish trim (bin/dist still ship). Residual hygiene: files still lists unused root *.d.ts (pack ships dist/*.d.ts only), and published scripts still advertise monorepo paths under unpackaged dirs.

Minimal fix: remove the unused *.d.ts entry; drop or relocate monorepo-only script entries from the published manifest.

[cursor]

Review verdict

REQUEST_CHANGES — Two independent HIGHs (dependency-runtime-surface, docs-and-positioning) plus 4/4 consensus that CHANGELOG’s “byte-identical” / “Nothing you get out changes” claim overstates codegen (and conflates it with the esbuild pin) without a golden lock. Proof files[] hardening is sound for CLI/dist but silently breaks --restart-on-runner-change for npm installs.

Perspectives: dependency-runtime-surface, release-discipline, docs-and-positioning, dx-and-examples → judge. Models: grok-4.5 (high) / composer-2.5.

Consensus findings

1. HIGH — CHANGELOG “byte-identical” / “Nothing you get out changes” overclaims across four @graphql-codegen/* majors (+ blankets esbuild). Soften wording and/or add a golden before release.
2. MED — codegen majors land cleanly on imports, but lack an output-stability lock (substring e2e only).
3. MED — dropping src/scripts from proof files[] is correct for the published CLI/dist story, but makes --restart-on-runner-change a silent no-op for npm/tarball installs.
4. LOW — esbuild 0.15.1→0.25.0 under-tested for non-trivial loadConfig() fixtures.

Coverage plan

• packages/codegen e2e — golden hash/snapshot of full graphql.ts for a fixed schema; empty-variables document assert on *QueryVariables shape (reject silent {} → Record<PropertyKey, never> drift).
• packages/config load test — fixture with relative/local import under esbuild 0.25 externalize-deps.
• packages/proof — pack asserts bin/+dist/ present and src/+scripts/ absent; dist-only --restart-on-runner-change must warn/exit, never silent empty snapshot.

Suggested follow-ups

1. Edit CHANGELOG: drop or qualify “byte-identical”; split codegen vs esbuild bullets.
2. Add codegen golden (+ empty-vars) before any residual stability language.
3. Fix or document proof supervisor restart under dist-only npm installs.
4. Optional: esbuild fixture or “default configs only” note.

Reviewer scoreboard

• dependency-runtime-surface: REQUEST_CHANGES — strong (concrete typescript-operations@5 empty-object break)
• release-discipline: COMMENT — strong (pack/bin/exports + restart silent no-op)
• docs-and-positioning: REQUEST_CHANGES — strong (HIGH overclaim + codegen/esbuild conflation)
• dx-and-examples: COMMENT — good (restart + pack DX)

  

_{Sent by Cursor Automation: Flatbread PR Review}

[cursor]

severity: HIGH — flagged-by: dependency-runtime-surface, docs-and-positioning, release-discipline, dx-and-examples

risk: This bullet asserts “Nothing you get out changes” and “byte-identical files” across four @graphql-codegen/* majors (cli 5→6, typed-document-node 2→6, typescript 4→5, typescript-operations 4→5) and also blankets the @flatbread/config esbuild 0.15.1→0.25.0 pin. Tests only check substrings/TS compile, not full-file hashes. typescript-operations@5 documents empty-object emission {} → Record<PropertyKey, never> when documents exist.

minimal fix: Soften to schema-/behaviorally compatible (and note document-path typing may change), split codegen vs esbuild into separate bullets, or add a pinned-schema (+ empty-vars documents) golden/hash test and cite it before keeping any identity claim.

[cursor]

severity: MED — flagged-by: dependency-runtime-surface, release-discipline, docs-and-positioning, dx-and-examples

risk: Coordinated majors still resolve on import/generate/CodegenConfig (no source adapter needed), but they enable the operations typing break above with only substring e2e coverage and caret drift within the new majors — no output-contract lock.

minimal fix: Keep the bumps; add a schema-only (+ empty-variables documents) golden/hash assertion in packages/codegen e2e before asserting stability in release notes.

[cursor]

severity: MED — flagged-by: release-discipline, dx-and-examples, docs-and-positioning

(Attached to adjacent RIGHT-side context: pure-deletion hunk removed src/scripts above *.d.ts.)

risk: Dropping src/scripts from files[] is correct for CLI/dist/exports (pack inspection agrees), but proof-supervisor’s --restart-on-runner-change still snapshots ../src/*.ts and skips missing files silently — so npm/tarball installs get an undetectable no-op. Published package.json still lists scripts that invoke tsx src/... / scripts/... which are no longer in the tarball.

minimal fix: Snapshot dist/ when src/ is absent, or warn when the snapshot is empty with the flag set; optionally note monorepo-only scripts / supervisor self-hosting in CHANGELOG.

[cursor]

severity: LOW — flagged-by: release-discipline, dx-and-examples

risk: esbuild 0.15.1→0.25.0 drives every loadConfig() bundle via externalize-deps; existing AVA cases cover only trivial inline configs, not nested/node_modules or workspace-import paths.

minimal fix: Add a fixture config that imports a sibling/local package, or qualify the CHANGELOG esbuild line as smoke-tested on default configs only.

[cursor]

CI Root Cause

Status: third-party-failure

Failing checks:

• integration-nextjs (20.x, windows-latest): pnpm install --frozen-lockfile failed during sharp@0.30.7 libvips download (socket hang up)

Evidence:

• Job never left install. Log shows sharp: Downloading https://github.com/lovell/sharp-libvips/releases/download/v8.12.2/libvips-8.12.2-win32-x64.tar.br then sharp: Installation error: socket hang up and ELIFECYCLE exit 1.
• Same run also logged sqlite3 prebuild socket hang up (secondary network flake).
• Sibling matrix cells on SHA a9543f2 passed, including integration-nextjs (20.x, ubuntu-latest), integration-nextjs (20.x, macos-latest), integration-nextjs (22.x, windows-latest), and integration-sveltekit (20.x, windows-latest).
• This PR commit only touches codegen/esbuild/proof package manifests, CHANGELOG, and lockfile; it does not change install scripts that would uniquely break Windows Node 20.

Resolution steps:

1. Re-run the failed job (or the whole Pipeline workflow) for SHA a9543f2.
2. If sharp-libvips downloads keep failing across retries, check GitHub Releases / runner egress health; this is not a branch code defect.
3. No branch code change is warranted unless a retry reaches the Next.js integration steps and fails there.

No code changes were made because this failure is not caused by the branch.

  

_{Sent by Cursor Automation: Flatbread - Fix CI}