chore(fbs): pin flatc toolchain to 25.9.23 and guard codegen drift #83

2026-05-31T09:52:00Z

developer commented

2026-05-31 09:52:00 +00:00

What & why

Fixes the toolchain drift flagged in the "Notes" of #82. The committed
FlatBuffers bindings were generated by flatc 25.x (TS runtime
flatbuffers@25.9.23), but nothing pinned the compiler. On a box with an
older flatc — Debian's apt ships 23.5.26 — a regen silently churns
output and flips nullable-scalar builder defaults (= null ↔ 0). #82
shipped 5 report files from the wrong compiler as a result.

Approach (agreed with owner)

Unify the whole toolchain on 25.9.23 — the only version available as
an npm package and a prebuilt flatc binary and a Go tag — and
make the bindings reproducible + guarded.

Go module downgrade github.com/google/flatbuffers 25.12.19 →
25.9.23 in pkg/schema, pkg/transcoder, gateway, integration, so
the compiler and both runtimes match. (25.12.19 is not on npm, so the TS
runtime can't go up; we align down instead.)
Regenerated every schema with flatc 25.9.23. The only resulting
binding change is ui/frontend/src/proto/galaxy/fbs/order/command-item.ts
— the lone file still on the old optional-scalar builder default
(cmd_applied/cmd_error_code: 0/BigInt(0) → null). Inert in
practice: the TS side never builds those response-only fields (the
engine writes them in Go via pkg/transcoder/order.go), and the reader
accessors are unchanged. The 5 #12 report files already matched 25.9.23
(their only off-version delta was the eslint header, restored in #82).
Pinned the version in tooling: a flatc-check guard in ui/Makefile
(fbs-ts) and a new pkg/schema/fbs/Makefile (fbs-go); both refuse a
mismatched flatc and point at the release binary. Stale apt install hint
fixed.
CI guard: new path-filtered .gitea/workflows/fbs-codegen.yaml
downloads the pinned flatc, regenerates Go + TS, and fails on any diff —
catching both "forgot to regenerate" and "wrong flatc version".
Docs: required version + regen commands in pkg/schema/fbs/README.md.

Verification

No wire-format change. Go build/vet, transcoder roundtrip + engine
tests, pnpm check (0 errors) and the full vitest suite (888) all green.
Regeneration is idempotent: a second make fbs-go / make fbs-ts with
flatc 25.9.23 produces no further diff (the new CI guard's invariant).
Verified the guard's negative path: with apt's 23.5.26, flatc-check
fails with the download hint.

## What & why Fixes the toolchain drift flagged in the "Notes" of #82. The committed FlatBuffers bindings were generated by flatc **25.x** (TS runtime `flatbuffers@25.9.23`), but nothing pinned the compiler. On a box with an older flatc — Debian's apt ships **23.5.26** — a regen silently churns output and flips nullable-scalar builder defaults (`= null` ↔ `0`). #82 shipped 5 report files from the wrong compiler as a result. ## Approach (agreed with owner) Unify the whole toolchain on **25.9.23** — the only version available as an npm package **and** a prebuilt `flatc` binary **and** a Go tag — and make the bindings reproducible + guarded. - **Go module downgrade** `github.com/google/flatbuffers` 25.12.19 → 25.9.23 in `pkg/schema`, `pkg/transcoder`, `gateway`, `integration`, so the compiler and both runtimes match. (25.12.19 is not on npm, so the TS runtime can't go up; we align down instead.) - **Regenerated every schema with flatc 25.9.23.** The *only* resulting binding change is `ui/frontend/src/proto/galaxy/fbs/order/command-item.ts` — the lone file still on the old optional-scalar builder default (`cmd_applied`/`cmd_error_code`: `0`/`BigInt(0)` → `null`). **Inert in practice:** the TS side never *builds* those response-only fields (the engine writes them in Go via `pkg/transcoder/order.go`), and the reader accessors are unchanged. The 5 #12 report files already matched 25.9.23 (their only off-version delta was the eslint header, restored in #82). - **Pinned the version in tooling:** a `flatc-check` guard in `ui/Makefile` (`fbs-ts`) and a new `pkg/schema/fbs/Makefile` (`fbs-go`); both refuse a mismatched flatc and point at the release binary. Stale apt install hint fixed. - **CI guard:** new path-filtered `.gitea/workflows/fbs-codegen.yaml` downloads the pinned flatc, regenerates Go + TS, and fails on any diff — catching both "forgot to regenerate" and "wrong flatc version". - **Docs:** required version + regen commands in `pkg/schema/fbs/README.md`. ## Verification - No wire-format change. Go `build`/`vet`, transcoder roundtrip + engine tests, `pnpm check` (0 errors) and the full vitest suite (888) all green. - Regeneration is idempotent: a second `make fbs-go` / `make fbs-ts` with flatc 25.9.23 produces no further diff (the new CI guard's invariant). - Verified the guard's negative path: with apt's 23.5.26, `flatc-check` fails with the download hint.

developer added 1 commit 2026-05-31 09:52:00 +00:00

chore(fbs): pin flatc toolchain to 25.9.23 and guard codegen drift

Tests · FBS codegen / codegen (push) Successful in 5s

Details

Tests · Go / test (push) Successful in 2m29s

Details

Tests · FBS codegen / codegen (pull_request) Successful in 6s

Details

Tests · UI / test (push) Waiting to run

Details

Tests · Integration / integration (pull_request) Successful in 1m46s

Details

Tests · Go / test (pull_request) Successful in 3m20s

Details

Tests · UI / test (pull_request) Successful in 3m19s

Details

658ab7f6e7

The committed FlatBuffers bindings were generated by flatc 25.x (the TS
runtime is flatbuffers@25.9.23), but nothing pinned the compiler, so a
regen on a box with an older flatc (Debian apt ships 23.5.26) silently
churns output and flips nullable-scalar builder defaults. PR #82 hit this
and shipped 5 report files from the wrong compiler.

Unify the whole toolchain on 25.9.23 (the only version available as an
npm package, a prebuilt flatc binary, and a Go tag) and make the bindings
reproducible:

- Downgrade the flatbuffers Go module 25.12.19 -> 25.9.23 (schema,
  transcoder, gateway, integration) so compiler and both runtimes match.
- Regenerate every schema with flatc 25.9.23. The only resulting change
  is order/command-item.ts: the lone straggler still on the old
  optional-scalar builder default (cmd_applied/cmd_error_code: 0 -> null).
  Inert in practice — the TS side never builds those response-only fields
  (the engine sets them in Go); the reader is unchanged.
- Pin the version in tooling: a flatc-check guard in ui/Makefile (fbs-ts)
  and a new pkg/schema/fbs/Makefile (fbs-go); both refuse a mismatched
  flatc and point at the release binary. Fix the stale apt install hint.
- Add a path-filtered CI guard (.gitea/workflows/fbs-codegen.yaml) that
  regenerates with the pinned flatc and fails on any diff.
- Document the pinned version and the regen commands in the schema README.

No wire-format change: Go build/vet, transcoder roundtrip + engine tests,
pnpm check and the full vitest suite (888) stay green.

owner approved these changes 2026-05-31 10:01:37 +00:00

developer merged commit bc838d72af into development

2026-05-31 10:02:23 +00:00

developer deleted branch feature/flatc-pin-25-9-23

2026-05-31 10:02:23 +00:00

developer referenced this issue from a commit

2026-05-31 10:15:33 +00:00

ci(ui-test): clean root-owned build artifacts so runner teardown succeeds

developer referenced this pull request

2026-05-31 10:15:53 +00:00

ci(ui-test): clean root-owned build artifacts so runner teardown succeeds #84

Sign in to join this conversation.