fix(hash): pin the service config-hash byte layout, decoupled from compose-go struct refactorings

[ndeloof]

What this PR does, in one sentence: the service config-hash byte layout is pinned to its historical form, so a compose-go struct refactoring can never again change hashes — and existing container stamps stay valid verbatim: no migration, no recreation.

Context

ServiceHash — the value behind com.docker.compose.config-hash, which decides whether up recreates a container — digests json.Marshal of types.ServiceConfig directly. encoding/json emits struct fields in declaration order and flattens embedded structs at their embedding position, so every recorded hash is silently coupled to compose-go's struct layout. That has held only because compose-go never reordered its fields: the upcoming container-spec layering (compose-spec/compose-go#866, adopted by #14093) regroups the whole struct, and without this fix its adoption would recreate every running container on the first up after upgrade — the very kind of undisclosed side effect the hash exists to prevent.

What the PR brings

• The hash re-emits the marshaled object with its root keys in a frozen list reproducing the historical order (generated by reflection over the last pre-layering compose-go — the last window where that order is observable in code), values byte-verbatim. Today the output is byte-identical to the direct marshal, proven by a continuity test; from the first struct reorder on, the frozen list alone carries that continuity, locked by golden-value tests. Full backward compatibility: not a single container, network or volume is touched by this change.
• Future attributes stay cheap: a root key missing from the list is appended in sorted order — deterministic, and thanks to omitempty only configurations using the new attribute see their hash move, exactly like a field addition always did. A reflection test fails when compose-go grows a root attribute absent from the list, keeping the hash surface a reviewed decision.
• The residual exposure is named and guarded: nested objects (deploy, healthcheck, …) keep their own struct marshal — a reorder inside one of them would still move hashes. The golden tests turn that from a silent side effect into a caught, reviewed event at the offending PR. Network and volume hashes are unchanged (their structs are not being reordered) and gain the same golden locks.
• The continuity test is deliberately transient: the compose-go upgrade that first reorders the struct deletes it in the same commit — the moment the frozen list takes over is explicit in history.

Why this is the right next brick

#14093 reorders ServiceConfig fields as a structural consequence of the jobs/container-spec work; landing this first means that PR ships with zero hash impact — nothing to put in its release notes — and any future compose-go layout change stays free as well.

🤖 Generated with Claude Code

[docker-agent]

Assessment: 🟢 APPROVE

The canonical-hash migration is well-reasoned and correctly implemented. The core canonicalHash approach (marshal → UseNumber decode into map[string]any → re-marshal with sorted keys) is sound and will be stable across compose-go struct reorderings. The dual-acceptance logic for volumes in reconcileVolumes is also correct: it recomputes the legacy hash from the current desired config, which correctly diverges when the config actually changed and matches only when unchanged.

The one finding the drafter flagged as medium — that legacyVolumeHash would compute the wrong legacy hash if a future compose-go upgrade reordered VolumeConfig fields — was dismissed by the verifier as an inherent limitation of the pre-existing legacy approach, consciously accepted and documented in the PR. The bridge only needs to survive until users' volumes have been recreated/updated once; afterward the canonical hash takes over and becomes layout-independent. This is a reasonable tradeoff given that volume recreation is destructive.

No CONFIRMED or LIKELY bugs were found in the introduced code.

[docker-agent]

Assessment: 🟡 NEEDS ATTENTION

One medium-severity finding in new test code introduced by this PR.

[codecov]

Codecov Report

❌ Patch coverage is 88.88889% with 4 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
pkg/compose/hash.go	88.88%	2 Missing and 2 partials ⚠️

📢 Thoughts on this report? Let us know!

[docker-agent]

Assessment: 🟢 APPROVE

The PR correctly pins the service config-hash byte layout using a frozen top-level key order, decoupling it from compose-go struct field ordering. The implementation is sound:

• pinRootKeyOrder correctly reconstructs JSON with frozen key ordering, using bytes.Buffer.Write (which never errors) and json.Marshal(key) (safe for plain strings)
• The sorted-append for unknown keys is deterministic and correct
• The golden test mechanism will catch future unintended hash changes
• The struct coverage test (TestServiceHashKeyOrderCoversStruct) ensures the frozen list stays in sync with compose-go via reflection
• The continuity test correctly validates byte-for-byte identity before compose-go reorders fields

No bugs were found in the introduced code.

[glours]

Reviewed the pinning mechanism itself (pinRootKeyOrder, the frozen serviceHashKeyOrder list, golden/continuity tests) and found it sound: verified the JSON re-serialization is byte-verbatim with no precision/escaping/duplicate-key issues, and cross-checked all 97 entries in serviceHashKeyOrder against the exact pinned compose-go version field-by-field with no gaps. go build, go test ./pkg/..., and golangci-lint are all clean on this branch.

Three small, non-blocking items below — a couple of reuse/dedup nits and one test-hardening suggestion for the reflection walker. None of these affect the correctness of the hash itself; happy to see this merge once you've had a look.

[docker-agent]

This review covers only the commits pushed since ce4e45db1dcd.

Assessment: 🟢 APPROVE

The incremental changes are a clean refactoring with no bugs introduced:

• trimServiceHashFields extraction is correct: types.ServiceConfig is passed and returned by value; ServiceHash captures the result with o = trimServiceHashFields(o), so all pointer-field nil-ings take effect. The Deploy deep-copy inside the function is preserved correctly.
• sortedKeys call replaces the equivalent inline sort-and-iterate loop. sortedKeys[V any](m map[string]V) []string is defined in pkg/compose/reconcile.go in the same package — in scope, correct signature, semantically identical to the removed code.
• "sort" import removal is safe: the only use of sort in hash.go was the now-replaced sort.Strings(rest) call.