Skip to content

Gate record — M1 (Core, CPU detection, dispatch framework)

  • Milestone: M1 per docs/prd/18-milestones.md
  • Objective: MOD-CORE, MOD-CPU, MOD-DISPATCH complete with scalar-only (empty) kernel tables; full build/test CI matrix live.
  • Date: 2026-07-02
  • Recorded per: REQ-MS-002
  • Result: PASS (CI-matrix evidence on the PR; two named deferrals in §7)

1. Files created

Public surface: include/quiver/quiver.h, include/quiver/core.h, include/quiver/dispatch.h, include/quiver/detail/config.h, include/quiver/detail/extern_decls.h (X-macro skeleton, empty inventory until M3). Implementation: src/cpu/cpu_features.h, src/cpu/cpu_features.cpp, src/dispatch/dispatch_internal.h, src/dispatch/dispatch_tables.cpp, src/dispatch/version.cpp. Tests: tests/CMakeLists.txt, tests/unit/test_main.cpp, tests/unit/test_core.cpp, tests/unit/test_dispatch.cpp. Docs: docs/architecture/core.md, docs/architecture/dispatch.md, docs/internals/cpu-detection.md, docs/internals/dispatch-state-machine.md, docs/internals/coding-standards.md, docs/api/core.md, docs/api/dispatch.md, this gate record.

2. Files modified

CMakeLists.txt (library target quiver::quiver, version parsed from config.h, tests subdir), CMakePresets.json (build + test presets), tests/… n/a (new), .github/workflows/ci.yml (build/test matrix ×14, ASan+UBSan, TSan, pinned clang-tidy jobs), .github/scripts/repo_lint.py (include-graph lint), .github/repo-manifest.json (M1 state), docs/mkdocs.yml (nav + snippet extraction), docs/architecture/module-map.md, README.md, CHANGELOG.md, docs/releases/gates/M0.md (post-gate addendum: operator actions completed).

3. Requirements satisfied (per PRD 18 M1 allocation)

REQ-CORE-001..004; REQ-INT-001; REQ-DISP-001..010, -012; REQ-API-001..005, -007; REQ-BUILD-001..008, -012; REQ-CI-002, -003, -010..012; REQ-TEST-010; REQ-STD-001, -003..006, -008; REQ-ERR-002, -005; REQ-REPO-005, -006, -009 (include lint enforced from here).

4. ADRs realized

ADR-002 (static library target), ADR-004 (lazy atomic dispatch + policy epoch, exactly the PRD 07 §6 protocol), ADR-005 (first-party CPUID/XGETBV + getauxval/sysctl), ADR-006 (façade pattern scaffolding: X-macro inventory + type-erased concrete-symbol registry), ADR-007 (quiver::v1 inline namespace), ADR-017 (contract model: QUIVER_ASSERT, fixed handler, noexcept surface).

5. Tests added

test_core (concept accept/reject, view triviality/layout, SumType mapping, assert death test with REQ-ERR-002 format regex, assert no-op test) and test_dispatch (version↔header match, monotonicity + platform sanity, detection purity, override round-trip, unsupported/out-of-range override rejection, synthetic-entry resolution, null-row skipping, epoch retraction, warmup idempotence, 8-thread concurrent-resolution test, QUIVER_ISA matrix via per-process probes: unset/scalar/case-mismatch/bogus/unsupported/supported). 14 tests; assert-dependent tests self-skip per REQ-TEST-014.

6. Commands run (local evidence)

# Command Result
1 cmake --preset dev && cmake --build --preset dev clean build, 0 warnings under -Wall -Wextra -Wpedantic -Wshadow -Wvla -Wconversion -Wsign-conversion + -fno-exceptions -fno-rtti
2 ctest --preset dev --output-on-failure 14/14 pass (1 designed skip: no-op-assert test under asserts-on)
3 cmake --preset release + build + ctest 14/14 pass (death test self-skips; no-op assert test runs — REQ-TEST-014 both directions)
4 cmake --preset asan-ubsan + build + ctest 14/14 pass, sanitizer-clean
5 cmake --preset tsan + build + ctest 14/14 pass — the ADR-004 protocol is TSan-validated locally (AppleClang)
6 uvx clang-format@18.1.8 --dry-run --Werror <all C++> clean (matches the CI pin exactly)
7 uvx clang-tidy@18.1.8 -p build/dev <src TUs> environmental failure only (see §7 deferral 2); one genuine finding fixed via NOLINT+reason (X-macro counting idiom)
8 python3 .github/scripts/repo_lint.py PASS incl. new include-graph lint
9 mkdocs build --strict -f docs/mkdocs.yml PASS (snippet extraction from tests/unit/test_dispatch.cpp verified by check_paths)
10 clang++ -fsyntax-only -arch x86_64 + native arm64 over all shipped TUs both architecture preprocessor paths verified locally after CI caught a missing <cstdint>/<cstddef> in the x86-only detect_x86() path (this host never compiles it natively) — cross-arch syntax checks are now part of local validation

7. Checks deferred (with reasons)

  1. CI matrix on real x86-64/ARM64/Linux runners (GCC 13/14, Clang 17/19, ARM64 legs, ubuntu ASan/UBSan/TSan, pinned clang-tidy-18) — runs on this PR; the M1 acceptance criterion "matrix + sanitizers green on x86-64, ARM64, macOS" is discharged by the PR checks (recorded in the PR).
  2. Local clang-tidy-18 — impossible on this machine: the local SDK's libc++ (LLVM-22 era, __is_convertible builtins) cannot be parsed by the clang-18 frontend. The CI clang-tidy job (ubuntu, clang-18 toolchain) is the authority for REQ-TEST-010.
  3. Gate+ deliberate-violation demos (M0 carry-over) — the format-violation negative is now demonstrable; executed as a temporary draft-PR check alongside docs-link and tree-manifest negatives, or evidenced by the required-checks configuration blocking red PRs (branch protection active since M0 addendum). Status: protection verified active; explicit red-PR demonstration remains open and is tracked for the M2 gate.

8. Scope exclusions (intentionally not implemented)

Kernels and kernel headers (M3/M6); MOD-KCOMMON (M3); testkit/bench harness (M2); QUIVER_PIN_ISA wiring (M8, REQ-DISP-013 — the option validates but does not yet pin); install/export (M8); nightly workflow (M3); fuzzing (M4).

9. PRD ambiguities

None blocking. One under-specification handled by the ambiguity policy:

  • REQ-DISP-007 state inventory vs REQ-DISP-005 read-once. REQ-DISP-007 fixes dispatch state as "exactly" four items (entry table, policy epoch, override slot, feature mask), but REQ-DISP-005's read-QUIVER_ISA-exactly-once mandate requires caching the parsed value somewhere. Implemented as a fifth constinit atomic (g_env_cap), documented in-source. Proposed smallest PRD amendment: extend the REQ-DISP-007 inventory with "one std::atomic<std::int8_t> environment-cap slot, populated together with the feature mask." No behavioral latitude was taken: read-once semantics, case-sensitivity, and ignore-rules follow REQ-DISP-005 exactly.

10. Deviations

  1. The CpuFeatures struct includes avx512vpopcntdq alongside the PRD 05 §4 illustrative field list (the same section's responsibilities text names VPOPCNTDQ detection; the struct literal omitted it). Local detail consistent with the normative text.
  2. The clang-17 CI legs pair the compiler with the runner image's gcc-13 libstdc++ via CXXFLAGS=--gcc-install-dir=… (clang-17 predates libstdc++-14's C++23 <tuple> and cannot compile GoogleTest against it). Classified as toolchain selection — the same environmental class as $CC/$CXX — not an ad-hoc flag set under REQ-BUILD-011.
  3. WERROR coverage follows the fixed preset list (REQ-BUILD-011 "presets only"): ci-gcc/ci-clang presets carry -Werror (Release); dev-preset legs run without -Werror. macOS legs run dev+release (no ci-appleclang preset exists in the REQ-BUILD-011 list).

11. Documentation rationale

Every M1 surface is documented in the same PR: two architecture pages, two API reference pages (with the code example snippet-extracted from the test suite per REQ-DOC-006), two internals pages (CPU detection tables; the dispatch memory-ordering argument), the coding-standards mirror, module-map/README/CHANGELOG updates. No documentation debt (REQ-DOC-012).

12. Final gate decision

PASS, conditional on the PR's full CI matrix turning green before merge (§7.1) — per the workflow, the merge itself is gated on those checks, so a merged PR constitutes the completed gate. Deferral §7.3 (explicit red-PR demo) carries to M2 without blocking: branch protection with required checks is active and verifiable.