refactor(resources): read the envelope constants from the contract, keep Decision A (backend#2220)

[shujaatTracebloc]

What

Third and last reader in the backend#2220 / RFC-BACKEND-664 §P0 consolidation. client-runtime#358 made the arithmetic single-definition; client#766 made both installers readers; this does the same for set.go.

Deleted: the four literals — the 1-CPU / 3-GiB overhead and the 1-core / 2-GiB floors. They now come from internal/resources/envelope_contract.json, vendored from client-runtime, whose arithmetic is node_sizing.envelope_from_allocatable.

cli#143 is amended in scope, not deviated from

Decision A stands, word for word:

• the number the user sets is the per-run ceiling, written to RESOURCE_* verbatim
• DeriveTraining is still the identity on it
• Overhead() is still a fit-check safety margin that is never subtracted

Every exported signature is unchanged and the existing suite passes untouched. What went away is the duplicate definition of four numbers, which was never part of that decision. The amendment is recorded on cli#143.

What the duplication actually cost

Not just tidiness. LargestReadyNode/nodeLarger ranks candidates (cpu, memory); the bash installer ranked them (memory, cpu). On a cluster of 8c/16Gi + 4c/32Gi those pick different nodes, so tracebloc resources set and the installer gave different answers about the same machine. Nobody chose that — it fell out of two independent implementations. The contract records one order, and this repo's is the one kept: it's what the user is shown when the wizard clamps their prompt.

Why this repo needs no generator

Unlike bash and PowerShell, Go can read JSON. go:embed takes the contract verbatim at compile time, so the vendored artifact is byte-identical to upstream and the cross-repo gate is a plain diff. No embed step, no regeneration, nothing to forget.

Two small design notes:

• The constants became funcs, not package vars, for the same reason Overhead() is a func: a var would be mutable from anywhere in the process, and the whole point is that one place decides these numbers.
• mustContractpanics on a malformed contract, MustCompile-style. The file is embedded at compile time, so it can only be invalid via a hand-edit or a botched re-vendor — a broken build, not a runtime condition a user could hit. A silent default here would be a fifth policy, which is exactly what this ticket removes. TestContractIsValid keeps the panic out of a release.

The drift gate fails closed

Per cli#536 (landed today): a check that never executed must not report as passing. client-runtime is private, so GITHUB_TOKEN can't read it — the job mints a least-privilege App token (repositories: client-runtime, contents: read, per the backend#2157 sweep) and fails rather than warning-and-skipping if that doesn't work.

It also re-derives upstream's vectors from upstream's own generator. A vendored contract can match upstream byte-for-byte while upstream's goldens have gone stale against upstream's code — mirroring that faithfully is still mirroring a lie.

Pinned via scripts/.client-runtime-ref, the same pin-don't-float convention this repo already uses for .client-ref and .data-ingestors-ref.

Verification

• go build, go vet clean; go test ./... — all packages ok
• gofmt and goimports clean; go.mod/go.sum untouched
• Verified the upstream-self-consistency step passes against the pinned ref locally
• Mutation-tested: overhead 3GiB → 4GiB in the vendored contract reddens 5 tests here — two of them pre-existing (TestOverhead_IsOneCoreThreeGiB, TestMaxRunCoresAndGiB). The existing suite already anchored these numbers independently, so the DoD holds in a consumer repo without me having written the test that proves it.

Where #2220 stands after this

Scope bullet	State
One accessor owned by client-runtime	✅ client-runtime#358
Installer stops computing it	✅ client#766
Installer stops writing RESOURCE_* unconditionally	⛔ not P0's to close — see below
set.go keeps its contract, drops its arithmetic	✅ this PR
Amendment comment on cli#143	✅ posted
Migration for edges already pinned by resources set	🔜 next PR

On the third bullet. If the installer stops writing RESOURCE_*, every edge falls to both-unset → the derive path → which is flag-off (DERIVE_JOB_ENVELOPE, backend#2167) → back to a flat cpu=2,memory=8Gi. That would undo backend#1236 fleet-wide and reinstate the unschedulable-8Gi bug on sub-8GiB machines. Turning derivation on needs #2167's concurrency answer, which is explicitly P4/L0. Recommend re-framing that bullet as half-P0 / half-P4 on the ticket rather than leaving it silently unticked.

Refs: RFC-BACKEND-664 §P0, client-runtime#358, client#766, cli#143, cli#536, backend#2167

🤖 Generated with Claude Code

---

Note

^{Cursor Bugbot is generating a summary for commit aa83178. Configure here.}

[saadqbal]

Reviewed as the third reader in the chain, and the cross-repo claim checks out end to end. I have all three repos on disk, so I verified byte-identity rather than trusting it:

4b37dde48131e34470f12cf981ce7abd5ca745d6d344183edb69f89a1fd6b7cb client-runtime@6293d15:envelope_contract.json
4b37dde48131e34470f12cf981ce7abd5ca745d6d344183edb69f89a1fd6b7cb client#766:scripts/tests/fixtures/envelope_contract.json
4b37dde48131e34470f12cf981ce7abd5ca745d6d344183edb69f89a1fd6b7cb cli#538:internal/resources/envelope_contract.json

Same digest all three, and both readers pin the identical upstream SHA. That's the property the whole consolidation rests on, and it holds.

go test ./internal/resources/... green, and mutation-tested both halves of the claim:

• Tamper the vendored overhead (cpu_millicores 1000 → 1500) → TestContractIsValid, TestGoldenVectorsReplay, plus the pre-existingTestOverhead_IsOneCoreThreeGiB, TestFitsNode_IncludesOverheadAndGPU and TestMaxRunCoresAndGiB all fail. So the vectors are derived and the old suite is genuinely still load-bearing.
• Make DeriveTraining subtract overhead (Decision A violated) → TestDecisionAIsIntact and the pre-existing TestDeriveTraining_IdentityUnderDecisionA both fail.

On "every exported signature is unchanged" — accurate, and I checked the surface rather than the diff summary. The only delta in set.go's exported funcs is minRunCPUMilli → minRunCPUMilli() inside two one-line bodies; the signatures are identical. Constants becoming funcs rather than package vars is the right call for the reason given: a var is mutable from anywhere in the process, and the point of this ticket is that one place decides.

mustContract panicking is correct here and the reasoning is the part I'd have wanted written down — the file is embedded at compile time, so invalidity means a hand-edit or a botched re-vendor, i.e. a broken build rather than a user-reachable condition. A silent default really would be a fifth policy. TestContractIsValid plus TestContractJSONIsCanonicalFormatting between them keep both the panic and a formatting-only re-vendor out of a release, which is more thorough than I expected.

Keeping this repo's (cpu, memory) order as the contract's is the right way round, for the reason stated — it's the number the user is shown when the wizard clamps their prompt, so the installers should move to it rather than the reverse.

Holding the approval only on CI:Lint, Test and Cursor Bugbot are all still in progress as I write (the scan had caught an earlier Lint failure; the current run is mid-flight). Nothing here needs another round from me — I'll approve next pass once they land green.

[saadqbal]

Approving as promised. Head is still 05517ed4 — the commit I reviewed — and CI is clean (24 passing, 3 skipped, nothing failing or pending), no open threads. Re-ran go test ./internal/resources/... on the current head: green.

Checked that drop the unreachable ContractVersion export didn't take the validation with it — contract.go:85 still panics on ContractVersion < 1, and contract_test.go:30 still asserts it, so what went was the redundant accessor rather than the guard.

Everything from my earlier pass stands: all three repos carry a byte-identical contract (4b37dde4…) at the same pinned client-runtime SHA, tampering the vendored overhead reddens five tests including the pre-existing ones, and making DeriveTraining subtract overhead reddens both Decision-A tests.

[LukasWodka]

/fr-pass