myxce/.kiro/specs/xce-harness-component/requirements.md

Requirements Document

Project Description (Input)

XCE engineers who build, deploy, and use xce_test — the REPL-driven wire-protocol test client that drives HA soak testing, multi-host allocation proof, resource-value verification, and WAL/snapshot inspection against controller/scheduler/worker — currently have no way to build, reference, or reason about it as a first-class component. Today xce_test's 15 source files live inside src/controller/testsuite/, its build target is defined inside src/controller/meson.build, and building controller implicitly produces it — despite xce_test having zero dependency on controller-private headers (verified: it only includes libxce public headers and the generated capnp schema). controller_unit_test also currently recompiles ~14 of xce_test's own source files a second time, paired with their white-box unit tests, further entangling it with the controller build.

This should change so that xce_test is promoted to a standalone src/harness/ component, following the project's existing C Daemon Layout Pattern (own meson.build, CLAUDE.md, include/, testsuite/) exactly like worker/ and scheduler/. It gets its own unit-test binary (carved out of the ~16 white-box tests currently trapped inside controller_unit_test) and its own explicit /xce-build harness entry, fully decoupled from /xce-build controller — building controller will no longer implicitly build it. Every downstream consumer that assumes the old coupling (/xce-test-ha, /xce-deploy-ha, /xce-test-multihost, /xce-test-resources skills) must be updated to build harness explicitly, and steering docs (build-deployment.md, structure.md, root CLAUDE.md) must reflect the new component. The binary itself keeps its current name, xce_test (per user decision — only the component/directory is renamed to harness); no xce_test behavior changes as part of this work. Full context, verified findings, and locked-in scope decisions: .kiro/specs/xce-harness-component/brief.md.

Introduction

xce_test is currently housed inside the controller component (src/controller/testsuite/, built from src/controller/meson.build) even though it has no structural dependency on controller internals — it is a network client that drives controller, scheduler, and worker over the wire. This entanglement means building the controller silently produces xce_test as a side effect, xce_test has no independent build entry point, and several of its own source files are re-compiled a second time inside the controller's unit-test binary alongside their white-box tests. This spec promotes xce_test to a standalone src/harness/ component with its own build target, unit-test suite, and documentation, fully decoupled from the controller build, while preserving xce_test's exact current behavior and binary name and updating every downstream workflow that depends on the old coupling.

Boundary Context (Optional)

• In scope: relocating xce_test's source files into a standalone src/harness/ component with its own build target, unit-test suite, and component documentation; making the harness independently buildable and no longer an implicit side effect of building the controller; updating every skill/workflow that currently assumes building the controller also produces the harness; updating steering documentation to describe the new component.
• Out of scope: any new xce_test capability, REPL command, or output-format change (owned by xce-test-cli-ux, xce-test-e2e-primitives, xce-test-rc-file, and future roadmap items such as the pending WAL/snapshot inspector work); renaming the xce_test binary; any change to xcecli, xceadmin, or the Go frontend build; reorganizing the controller's own domain unit tests (HA, persistence, commit, replication, job, etc.); adding xce_test to any nix/AppImage production package (it is not part of one today and stays that way).
• Adjacent expectations: the three existing xce-test-* specs continue to govern xce_test's behavior and are not reopened by this spec; their file-path references become stale after this move and should be refreshed as a follow-up, not as part of this spec's own acceptance criteria.
• Known limitation (accepted, verified during task 4.3): when a controller-only build's profile also runs the project's full registered test suite (the default asan profile), Meson's own test-runner rebuilds every registered test's build-order dependencies before filtering which tests actually run by --suite — including xce_test, via harness_unit_test's own dependency on it (Requirement 3.2). This means xce_test can still end up rebuilt on disk as a transitive side effect of a controller-only build's test-running step, even though the build's own explicit compile step never names it (Requirement 2.2, as narrowed). This is a documented Meson platform behavior, not a defect in this spec's implementation — verified deterministic and traced to a specific build-log mechanism, not a flake. Fixing it further would require either auditing and completing every component's explicit compile-target list to cover its full test suite (non-trivial: several components, including controller itself, already rely on this same auto-rebuild for test binaries not in their own explicit target list) or weakening harness_unit_test's build-order guarantee that Requirement 3.2 depends on (itself verified load-bearing in task 4.2) — both rejected as disproportionate to this spec's scope. Requirement 2.2 is scoped to what the build system directly controls (its own explicit compile step).

Requirements

Requirement 1: Standalone Component Structure

Objective: As an XCE engineer, I want xce_test organized as its own top-level component, so that I can build, navigate, and reason about it independently of the controller.

Acceptance Criteria

1. The harness component shall exist as its own top-level directory, independent of the controller component's directory.
2. The harness component shall provide its own build definition, its own component documentation, and its own test directory, matching the structure that other standalone components (worker, scheduler) provide.
3. The harness component shall retain the xce_test binary name unchanged.
4. The harness component shall have no dependency on any controller-private source file or header.

Requirement 2: Independent, Decoupled Build

Objective: As an XCE engineer, I want to build the harness independently of the controller, so that building one does not implicitly build or silently omit the other.

Acceptance Criteria

1. When an engineer requests a harness-only build, the XCE build system shall produce the xce_test binary without requiring a controller build.
2. When an engineer requests a controller-only build, the XCE build system's explicit compile step shall not name xce_test as a target.
3. The XCE build system shall expose the harness as its own selectable build component, listed alongside the project's existing components (lib, controller, scheduler, worker, apiserver, xcecli, xceadmin).
4. When an engineer requests a build of all components, the XCE build system shall include the harness component's binary in the result.

Requirement 3: Unit Test Coverage Continuity

Objective: As an XCE engineer relying on automated tests, I want the harness's existing white-box unit tests to keep running after the move, so that no test coverage is silently lost or misattributed.

Acceptance Criteria

1. When the harness component is built and tested, the XCE build system shall run every unit test that validates one of xce_test's own source files, with the same pass/fail semantics those tests had before the move.
2. If a unit test validates one of xce_test's own source files, then that test shall run and report as part of the harness component's own test suite, not the controller's, after the move.
3. The controller's unit test suite shall continue to run every test that does not validate an xce_test source file, unaffected by this change.
4. The harness component's test results shall be reported under a test suite name distinct from the controller's, so pass/fail outcomes are attributable to the harness specifically.

Requirement 4: Behavioral Parity

Objective: As an engineer or operator using xce_test day to day, I want its behavior to be completely unchanged by this restructuring, so that existing scripts, muscle memory, and documentation referencing xce_test keep working.

Acceptance Criteria

1. The harness component shall preserve every xce_test REPL command, command-line flag, and output format exactly as it behaved before the move.
2. When xce_test is invoked with any command-line flag or REPL command that existed before the move, the harness component shall produce output identical to its pre-move behavior.
3. The harness component shall not introduce any new xce_test command, flag, or output change as part of this restructuring.

Requirement 5: Downstream Workflow Compatibility

Objective: As an XCE engineer running HA soak tests, multi-host verification, resource verification, or a local cluster deployment, I want my existing workflows to keep working after xce_test is decoupled from the controller build, so this restructuring does not silently break the tooling I rely on.

Acceptance Criteria

1. When an engineer runs the HA soak test workflow, that workflow shall ensure the harness is built before it is needed, without relying on a controller build having produced it.
2. When an engineer runs the local HA cluster deployment workflow, that workflow shall ensure the harness is built or shall clearly report that it is missing, rather than silently assuming it exists because the controller was built.
3. When an engineer runs the multi-host verification workflow or the resource-value verification workflow, that workflow shall ensure the harness is built before it is used.
4. If a downstream workflow requires the harness binary and it has not been built, then that workflow shall report a clear, actionable message rather than failing with an unrelated error or silently skipping the step that depends on it.

Requirement 6: Documentation and Steering Consistency

Objective: As an XCE engineer reading project documentation, I want the steering docs and component guides to accurately describe the harness as a standalone component, so that I don't rely on stale information about where xce_test lives or how it's built.

Acceptance Criteria

1. The harness component shall have its own component guide describing its purpose, build command, and structure, consistent with the guides other standalone components have.
2. The project's build and deployment documentation shall describe the harness as an independently buildable component and shall no longer state that building the controller also builds xce_test.
3. The project's structure documentation shall list the harness component alongside the project's other component directories.