docs(xce-harness-component): list harness in structure.md

Add harness to structure.md's top-level src/ directory tree (after
controller/) and extend the flat-root Exceptions bullet to cover it
alongside controller. Verified against the real src/harness/ layout
(14 flat .c files, no nested src/, own include/ and testsuite/).

This completes Major Task 3 (Integration) -- all downstream skills and
steering docs now correctly describe the harness component.

Task 3.7 of xce-harness-component.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RLSNJhNoULvVcUhXEFafQC
This commit is contained in:
Rongsong Shen 2026-09-14 07:56:15 +00:00
parent 6318183b67
commit 64e4ccb308
No known key found for this signature in database
GPG key ID: 5BCDAAE0123E9FE2
2 changed files with 4 additions and 2 deletions

View file

@ -67,7 +67,7 @@
- _Requirements: 6.1, 6.2_
- _Boundary: CLAUDE.md, build-deployment.md_
- _Depends: 3.1_
- [ ] 3.7 (P) Update structure steering to list the harness component
- [x] 3.7 (P) Update structure steering to list the harness component
- Add `harness` to `structure.md`'s component table and to its flat-root Exceptions list alongside controller
- Observable: `structure.md`'s component tree and Exceptions section both mention harness
- _Requirements: 6.3_
@ -102,5 +102,6 @@
- **Task 1.1**: `test_test_cli.c`/`test_xcetest_process_entry.c` locate `xce_test` as a build-dir sibling via `resolve_xce_test_path()`. Since they still live in `src/controller/testsuite/` until task 2.1, a temporary `xce_test_controller_link` custom_target symlink bridge was added to `src/controller/meson.build` (documented in-code as removable once task 2.1 relocates both files). Task 2.1 must remove this custom_target and the `test()`'s `depends:` on it as part of that relocation.
- **Task 1.1 gotcha**: a meson `custom_target` command's `@INPUT0@`/`@OUTPUT0@` tokens expand to build-root-relative paths, but a symlink's target string is resolved relative to the *symlink's own directory* at dereference time, not the invocation cwd or the string's own reference frame — using `@INPUT0@` directly as an `ln -sf` target from a different subdirectory produces a broken link. Use an explicit `../`-relative (or absolute) path instead.
- **Build dir note**: this repo's default build dir resolves to `src/xce.build/` (relative to `src/tools/xce-build.sh`'s own cwd), not a bare `xce.build/` at the repo root.
- **Task 3.7**: Major Task 3 (Integration) is now fully complete. Task 3.6's review round caught a real doc-consistency miss (a partial fix left a contradicting stale claim elsewhere in the same file); the lesson (full end-to-end file re-read, not just the two named spots) was applied successfully in 3.7 and independently confirmed by review. Non-blocking follow-up noted for a future pass: `structure.md` line 92's generic "`test.c` provides the test runner harness" line is doubly stale (controller's runner is `controller_test.c`, harness's is `harness_test.c`) and also coincidentally collides with `src/harness/test.c`, which is real production code (xce_test's REPL entry point), not a test runner — worth a one-line correction sometime, out of this spec's boundary.
- **Task 2.2**: Major Task 2 (Core) is now fully complete — all 5 harness test binaries exist under `suite: 'harness'` (4/20/5/12/132 tests, all green), controller's suite is fully clean at 1199 tests. Minor non-blocking cleanup found for a future pass: `src/controller/meson.build:211`'s `struct2json_dep` comment still cites `test_listfmt_json.c` (relocated to harness in task 2.1) as a consumer, and its own dependency may now be unused in `controller_unit_test_deps` — worth checking whether it can be dropped entirely once someone audits it.
- **Task 2.1**: confirmed `resolve_xce_test_path()` (`/proc/self/exe` dirname + sibling lookup) needed zero code change once both `xce_test` and `harness_unit_test` build under the same `src/harness/meson.build` — they land in the same build-dir subdir automatically. Test counts cross-checked and consistent end to end: 1331 (pre-move) → 1228 (after task 1.1's 11-entry removal) → 1199 controller + 132 harness = 1331 (after task 2.1). Minor non-blocking nit for a future pass: `test_xcetest_process_entry.c`'s header comment still describes the old controller-embedded build layout — stale prose only, not a functional issue.

View file

@ -10,6 +10,7 @@ src/
│ ├── raft/ C — reusable Raft consensus module (raft.c/raft.h)
│ └── testsuite/ C — libxce unit tests (test_*.c)
├── controller/ C — cluster controller daemon
├── harness/ C — xce_test wire-protocol test/verification CLI + WAL/snapshot inspection utilities
├── worker/ C — per-node job execution daemon (xcecd)
├── scheduler/ C — job scheduling engine (plugin architecture)
├── autoscaler/ C — autoscaling engine (provider plugins)
@ -35,7 +36,7 @@ src/<component>/
```
**Exceptions**:
- `controller/` keeps its `.c` files flat in the component root (not in a nested `src/`), and does have its own `testsuite/`.
- `controller/` and `harness/` both keep their `.c` files flat in the component root (not in a nested `src/`), and each has its own `testsuite/`.
- `worker/` has no `testsuite/` — no `test_*.c` files exist anywhere in the component.
- `autoscaler/` does not follow this pattern at all: it has no CLAUDE.md, and its daemon code lives two levels deeper in `src/autoscaler/scaler/` (flat `.c` files plus its own `include/` and `testsuite/`), alongside `src/autoscaler/providers/`.