myxce/.kiro/specs/build-time-versioning/requirements.md

Requirements Document

Project Description (Input)

Build-time versioning: every component (controller, scheduler, worker, apiserver, xcecli, xceadmin) must embed and display its source git commit id and build timestamp, shown both via a --version CLI flag and a startup log line (INFO level, matching existing daemon startup log conventions). xce-build.sh should also ensure/verify this info is correctly embedded for each component it builds. No existing infrastructure for this exists today (confirmed via investigation: no version.h/version.c, no meson version defines, no Go ldflags -X injection, no --version handling in any daemon, no dynamic pyproject versioning) -- this is new, cross-cutting work spanning three toolchains: C/meson (controller/scheduler/worker, linking libxce), Go (apiserver/xcecli, via ldflags), and Python (xceadmin, via pyproject/meson custom_target). Motivating incident: a live production-like deployment kept running a stale debug-profile scheduler binary that lacked a just-landed heap-corruption fix, and diagnosing that required manual ls -la mtime checks plus git merge-base --is-ancestor -- this feature should make that kind of staleness immediately visible from the running binary/log itself, no forensic git commands needed.

Introduction

This feature adds build-time version identification to every XCE component so operators can determine, directly from a running binary or its log output, exactly which source commit and build time produced it — without resorting to manual filesystem or git forensics. It is motivated by an incident where a stale scheduler binary silently kept running a known-fixed heap-corruption bug because there was no way to tell, from the binary or its logs, which commit it was actually built from.

Boundary Context (Optional)

• In scope: embedding and displaying a git commit identifier and build timestamp for controller, scheduler, worker, apiserver, xcecli, and xceadmin; exposing this via a --version flag and, for long-running daemons, a startup log line; the build tooling confirming this information was correctly embedded for each component it builds.
• Out of scope: automatically detecting or alerting that a running/deployed binary is stale relative to the latest source; retroactively updating the version information of an already-running process; version negotiation or compatibility checks between components running different versions.
• Adjacent expectations: operators are expected to compare the displayed commit identifier against the source repository themselves (for example, via git) to judge staleness; this feature makes that comparison possible, it does not automate it.

Requirements

Requirement 1: Version Information Content

Objective: As an operator diagnosing a running deployment, I want each component to know which exact source commit and build time produced it, so that I can determine whether a binary reflects a given fix without inspecting file timestamps or git history by hand.

Acceptance Criteria

1. The system shall associate a git commit identifier with every built artifact of controller, scheduler, worker, apiserver, xcecli, and xceadmin.
2. The system shall associate a build timestamp, in absolute UTC form, with every built artifact of controller, scheduler, worker, apiserver, xcecli, and xceadmin.
3. If the source tree contains uncommitted changes at build time, then the system shall mark the associated version information as modified, so an operator does not mistake it for an exact committed state.
4. If the git commit identifier cannot be determined at build time (for example, a source tree without git history), then the system shall record the version information as unknown rather than fail the build.

Requirement 2: Version Display via CLI

Objective: As an operator or script, I want to query a component's build identity directly from its binary, so that I can verify a deployed artifact without needing separate log access.

Acceptance Criteria

1. When a --version flag is passed to the controller, scheduler, worker, apiserver, xcecli, or xceadmin command, the invoked component shall print its associated commit identifier and build timestamp and exit without performing its normal function.
2. The system shall present the same commit identifier and build timestamp values through the --version flag and through the startup log line (Requirement 3) for the same build artifact, so the two never disagree.

Requirement 3: Version Display at Startup

Objective: As an operator watching a daemon's log output, I want to see its build identity as soon as it starts, so that I can confirm which commit is actually running without a separate query step.

Acceptance Criteria

1. When the controller, scheduler, worker, or apiserver daemon starts, the daemon shall log its commit identifier and build timestamp at INFO level, following the daemon's existing startup log format.
2. While a controller, scheduler, worker, or apiserver daemon is running, an operator shall be able to determine its build identity by reading its log without sending it any request.

Requirement 4: Build-Time Embedding Verification

Objective: As a developer running the project's build tooling, I want confirmation that version information was actually embedded correctly, so that I do not unknowingly ship or deploy a binary with missing or incorrect build identity.

Acceptance Criteria

1. When the build tooling builds a component covered by this feature, the build tooling shall confirm that a commit identifier and build timestamp were embedded in the resulting artifact for that component.
2. If the build tooling cannot confirm that version information was embedded for a component it built, then the build tooling shall report this as a build problem rather than silently succeeding.
3. The system shall embed accurate version information under every supported build profile of controller, scheduler, and worker, not only a subset of profiles.

Requirement 5: Accuracy of Embedded Version Information

Objective: As an operator relying on displayed version information to make a deployment decision, I want that information to always reflect the actual source tree and build event that produced the running binary, so that I can trust it during an incident.

Acceptance Criteria

1. The system shall derive the embedded commit identifier from the actual state of the source tree at build time, not from a value set independently of the build.
2. The system shall derive the embedded build timestamp from the actual time the build artifact was produced, not from the source commit's own timestamp.