v4.0.0 — Schema-Metadata Emission (po's first major bump) — phases 229–231
Ships po's first ALWAYS-ON new generated artifacts, so that adjacent
hand-written sqlx references schema names through Go identifiers instead of
string literals — and therefore fails to compile when a column is renamed or
dropped. po gains no analytics; this only removes the brittleness of string
literals in the raw SQL coexisting on the same *sqlx.DB.
Two new unconditional files:
- <persistence-dir>/00_meta_types.gen.go — the 34-field wire contract:
TableMeta (7) / ColumnMeta (9) / FK (7) / Index (11)
- <persistence-dir>/<entity>/meta.gen.go — var Meta + var Columns
Why a MAJOR bump: the default generated output changes for every existing po
user. Emission is gated by nothing — no flag, no po: directive — because
opt-in metadata rots stale, and false metadata is worse than absent metadata.
BREAKING: seven identifiers are now emitted with no opt-out. Root persistence
package: TableMeta, ColumnMeta, FK, Index (FK and Index are the high-collision
names). Each entity package: Meta, Columns, metaColumns. A pre-existing
hand-written declaration of any of them becomes 'redeclared in this block' on
the next po generate; the remedy is to rename your own symbol.
The guarantee is name-sync ONLY — SQL correctness is not checked, and
Meta.ForeignKeys' map keys are runtime strings that give no compile-time
safety. Only the Columns namespace-struct does.
Contract: ADR-0024 (docs/adr/0024-schema-metadata-wire-contract.md), LOCKED.
Migration: MIGRATION.md, section v3.24.0 -> v4.0.0.
Gates: all green — make check (incl. cover-check), check-integration, vuln,
lint at the golangci zero-issue baseline; ratchet 117/62/22/40/5 held
down-only; 0 net-new runtime deps (the x/text 0.38.0 -> 0.39.0 bump closing
GO-2026-5970 is a patch bump of an existing indirect dep).
Additive non-regression proven by a two-generate comparison across the version
boundary: 260 -> 293 files, 33 new, 0 removed, 0 content diffs in any
pre-existing generated file.