[architect] refactor: single source of truth for CPU-arch identity — new include/arch.yml, k3s-bin.bst, k3s-sysext.bst, os-release-flatcar.bst, extension-release.k3s

[kubestellar-hive]

Claimed cluster

Exact ground this PR occupies, for the next occupied-ground comparison:

• New file: include/arch.yml
• elements/k3s/k3s-bin.bst — config.install-commands (adds a guard command; the existing install line is unchanged)
• elements/oci/k3s-sysext.bst — the top-level (@) include and the extension-release.d staging lines inside install-commands
• elements/bluefin-server/os-release-flatcar.bst — the top-level (@) include and the FLATCAR_BOARD= line
• files/k3s/sysext/extension-release.k3s — removes the ARCHITECTURE= line

Does not touch project.conf, Justfile, .pre-commit-config.yaml, AGENTS.md, .github/, docs/, tests/, elements/installer/, elements/oci/bluefin-server-installer.bst, elements/oci/bluefin-server-ddi.bst, elements/bluefin-server/os-stack.bst, elements/bluefin-server/os-sshd-config.bst, files/os/, or files/k3s/sysext/{k3s.service,k3s-agent.service,50-bluefin-tuning.yaml,k3s-bluefin.conf}.

Disjoint from every open PR on this repo: #34 (project.conf release-version / Justfile validate / .pre-commit-config.yaml), #36 (os-stack.bst + sysupdate keyring + docs), #37 (files/os/justfile), #38 and #30 (tests/), #29 (sshd), #22/#25/#26/#27 (installer + PXE elements and docs), #18 and #21 (workflow/deps). No file in this PR appears in any of them.

Fixes the arch-identity axis only. It deliberately does not touch the release-version axis (#31/#34) or the sysext-versioning question in #32.

Refactor

project.conf declares a real, selectable build axis and binds it to a variable:

options:
  arch:
    type: arch
    variable: arch
    values: [aarch64, x86_64]
sandbox:
  build-arch: "%{arch}"

elements/freedesktop-sdk.bst honours it with an explicit arch == 'aarch64' branch, so the axis is not vestigial. Three downstream sites then restated the architecture as an unguarded x86_64 literal in three different vendor spellings, with nothing comparing them to %{arch}:

Site	Literal	Consumer
elements/k3s/k3s-bin.bst sources[0].url	the upstream amd64 k3s asset (SHA from sha256sum-amd64.txt, per the element's own docstring)	installed unconditionally at /usr/bin/k3s
files/k3s/sysext/extension-release.k3s	ARCHITECTURE=x86-64	copied byte-for-byte into /usr/lib/extension-release.d/
elements/bluefin-server/os-release-flatcar.bst	FLATCAR_BOARD="amd64-usr"	written into /usr/lib/os-release

Failure mode this closes

bst build -o arch aarch64 oci/k3s-sysext.bst succeeds today. There is no error surface on the arch axis anywhere in the graph: an x86-64 k3s ELF lands in an aarch64 rootfs, the sysext advertises ARCHITECTURE=x86-64 so systemd-sysext silently refuses to merge it (k3s never appears, on a green build), and /usr/lib/os-release advertises FLATCAR_BOARD=amd64-usr, which is the key third-party Flatcar extension matching uses. Quiet in exactly the way the release-version drift in #31 was quiet.

Changes

1. include/arch.yml — the one place the vendor spellings of the arch axis are written: %{systemd-arch} (x86-64 / arm64) and %{flatcar-board} (amd64-usr / arm64-usr), selected with a (?) conditional on arch, using the same shape as the existing conditional in elements/freedesktop-sdk.bst. Because project.conf constrains options.arch.values to those two architectures, an unmapped architecture cannot be selected.
2. elements/oci/k3s-sysext.bst includes it and appends ARCHITECTURE=%{systemd-arch} to the staged extension-release file.
3. files/k3s/sysext/extension-release.k3s drops its ARCHITECTURE= line, so that field now has exactly one producer instead of two.
4. elements/bluefin-server/os-release-flatcar.bst includes it and emits FLATCAR_BOARD="%{flatcar-board}".
5. elements/k3s/k3s-bin.bst asserts %{arch} == x86_64 before installing, so the amd64-only pin is an explicit, loud constraint. Adding the k3s-arm64 source is a separate, deliberate change and is not made here — this PR does not enable aarch64, it stops aarch64 from silently mis-building.

This is the repo's own red flag from docs/skills/avoid-over-engineering.md — "The same value hardcoded in more than one file" — applied to the arch axis rather than the version axis.

No behavior change on the supported path

With arch == x86_64 the generated values are byte-identical to the literals they replace:

• ARCHITECTURE=x86-64 — same line, same position (appended after VERSION_ID, which was already its position in the static file)
• FLATCAR_BOARD="amd64-usr" — same line
• install -D -m 0755 k3s ... — unchanged, now preceded by a guard that is a no-op on x86_64

Release asset names, the DDI/UKI/installer graph, and files/os/sysupdate.d/*.transfer are untouched.

Verification

All five files parse as YAML, and the (?) structure matches the shape BuildStream already consumes in elements/freedesktop-sdk.bst:

OK include/arch.yml
OK elements/oci/k3s-sysext.bst
OK elements/bluefin-server/os-release-flatcar.bst
OK elements/k3s/k3s-bin.bst
OK project.conf

{'variables': {'(?)': [{'arch == "x86_64"':  {'systemd-arch': 'x86-64', 'flatcar-board': 'amd64-usr'}},
                       {'arch == "aarch64"': {'systemd-arch': 'arm64',  'flatcar-board': 'arm64-usr'}}]}}

Reviewer note — just validate was not run. This session has no podman and no bst, so the bst show --deps all graph check could not be executed. A maintainer should run just validate before merging; the specific thing to confirm is that BuildStream composes the element-level (@): include/arch.yml fragment's variables block with each element's own variables block (strip-binaries: "" in both consumers) rather than replacing it.

Follow-up deliberately not bundled

The release assets (k3s-<ver>.raw.zst, the DDI, the UKI, the installer) carry no arch component in their filenames, and files/os/sysupdate.d/70-k3s.transfer fetches by that name from releases/latest/download/. Once a second architecture is actually built, two arch builds of the same release produce identically named assets and one would overwrite the other in the fleet's update path. Arch-qualifying the asset names is a release-contract change that also moves the MatchPatterns in files/os/sysupdate.d/, overlaps the ground of #34, and should be tracked on its own.

Refs #39

---

Filed by architect agent (ACMM L5 — hold-gated mode). Hold-gated: human review required. Structural only — no behavior change on the x86_64 path; do not merge without a maintainer just validate run.

— hive: agent=architect backend=copilot model=claude-opus-5

[hanthor]

Verified project.conf's options.arch and elements/freedesktop-sdk.bst's existing (?) conditional shape match the new include/arch.yml pattern; no behavior change on the x86_64 path confirmed line-by-line. CI green.

---

Generated by Claude Code

[castrojo]

Approved by @castrojo for Hive auto-merge on green CI.