V2.10.S2: Build.zig module registry and walk-based discovery

[deeprnd]

V2.10.S2: Build.zig module registry and walk-based discovery

Status: Backlog
Epic: #[github-epic-issue]
Parent roadmap item: V2.10: Build System Consolidation And Qt Build Validation
Labels: type/story, area/platform

Refactor build.zig from its current ~1,766 lines into a <500-line declarative
build script with a module registry, walk-based test discovery, and utility
functions for import resolution and link helper application. No manual copy/paste
of per-file b.createModule + b.addTest blocks — a single registration loop
handles the pattern.

Product Outcome

Developers can add a new Zig test file without touching build.zig (except for
the optional module registry entry). Adding a test file drops from 20+ lines of
manual boilerplate to a zero-line change if the file falls under a declared
discovery path. This removes a structural barrier to community contribution.

User Story

As a developer adding a new Zig module with test {} blocks, I want
build.zig to auto-discover and register it, so that I don't need to read
existing entries, copy boilerplate, and carefully set imports and link helpers
for each of the three test lanes.

Scope

• In scope: create a module registry at the top of build.zig declaring
  ~15–20 named modules (name → path + imports).
• In scope: implement a walk function that iterates over src/tickoni/ paths
  with configurable include/exclude glob patterns, sorted alphabetically for
  determinism.
• in scope: implement import resolution from the module registry based on the
  file's containing directory.
• In scope: implement link helper application by path convention
  (e.g., c_abi/* → linkTickoniCodec, tiles/*/mod.zig importing c_abi →
  linkTickoniFiredancer).
• In scope: refactor the unit/cov test registration into a single walk loop;
  the cov lane reuses unit test artifacts with installArtifact instead of
  runArtifact.
• In scope: refactor the integration test lane into a separate walk loop that
  creates fresh module instances per lane.
• In scope: preserve addPlainTestRun for process-mode tests.
• In scope: preserve existing link helper functions unchanged.
• In scope: all existing tests (unit, integration, cov) pass after the refactor.
• Out of scope: changes to CI pipeline structure (.github/workflows/).
• Out of scope: changes to Firedancer C shim files or build.
• Out of scope: build-time caching or incremental build optimization.

Preconditions And Assumptions

• The current build.zig at ~1,766 lines has ~1,400 lines (80%) of copy/paste
  boilerplate for test declarations across unit, integration, and cov lanes.
• The link helper functions (linkTickoniCodec, linkTickoniFiredancer,
  linkTickoniTopoRun, linkTickoniTileRun) are correctly abstracted but
  invoked manually per test step.
• build.zig is a Zig build script, not Zig source code — the <500-line target
  refers to lines of build script text.

Acceptance Criteria

• Given a new .zig file under src/tickoni/ with test {} blocks, when
  zig build test runs, then build.zig discovers it via the walk,
  resolves imports from the module registry, applies the correct link
  helpers, and registers the test binary.
• build.zig is <500 lines after the refactor.
• The module registry is clearly structured as name → path + imports
  mappings at the top of the file.
• Walk functions are deterministic: discovered file paths are sorted
  alphabetically.
• zig build test passes all existing unit tests.
• zig build test --summary all passes all existing integration tests.
• just test-cov-tk (or zig build cov) passes.
• The walk does not auto-parse @import() calls — module declarations
  remain explicit in the registry.
• Files that don't match any declared module are handled gracefully
  (e.g., skipped with a log message, not crashing the build).
• Cov lane reuses unit test artifacts via installArtifact — no separate
  walk loop for cov.
• Integration tests use separate module instances from unit tests.

Conditional Acceptance

Financial capability and policy

• N/A - story modifies build.zig (build script); no policy changes.

Audit and replay

• N/A - story modifies build.zig (build script); no audit/replay changes.

Runtime topology and tile ownership

• N/A - story modifies build.zig (build script); no topology changes.

Model, tool, adapter, or execution boundary

• N/A - story modifies build.zig (build script); no model/adapter/execution changes.

CaseOps API or UI

• N/A - story modifies build.zig (build script); no API/UI changes.

Storage role: Memory, Analytics, Ledger

• N/A - story modifies build.zig (build script); no storage changes.

Metrics, diagnostics, and operations

• N/A - story modifies build.zig (build script); no metrics/telemetry changes.

Evidence Plan

• Demo or command: zig build test, zig build test --summary all,
  zig build cov, and confirm line count of build.zig.
• Tests: All existing unit, integration, and cov tests pass.
• Fixtures or samples: Module registry declaration.
• Audit/replay evidence: N/A - build script only.
• Blocked-flow evidence: A file outside all discovery paths is ignored without
  build failure.

Quality Gate

• build.zig line count < 500.
• zig build test passes.
• zig build test --summary all passes.
• zig build cov passes.
• Walk order is sorted alphabetically.
• No auto-import parsing — module registry remains explicit.
• Documentation and roadmap status are updated.

Notes And Open Questions

• Module registry format: { "name", .{ .path = ..., .imports = ... } } vs
  inline addModule calls. Spike the more readable option.
• Import resolution: per-directory nearest-module lookup vs per-file override
  map. Spike based on how many files need overrides.
• Link helper inference: path-based convention vs explicit metadata on module
  declarations. Spike for correctness guarantees.
• Cov lane: reuse unit artifacts with installArtifact wrapper or separate
  walk. Spike for build efficiency.