ci: V-model pipeline for native-ci and GitHub CI (Refs #254)

.config/nextest.toml

@@ -0,0 +1,28 @@
+# cargo-nextest configuration (Refs #254).
+#
+# `default` is what developers get locally. `ci` is selected in the workflows
+# with `--profile ci`: no fail-fast so one red target does not hide the rest,
+# JUnit output for the runner to archive, and bounded retries only for tests
+# that are known to depend on a live terraphim_server process.
+
+[profile.default]
+retries = 0
+fail-fast = true
+slow-timeout = { period = "60s", terminate-after = 3 }
+
+[profile.ci]
+retries = 0
+fail-fast = false
+slow-timeout = { period = "60s", terminate-after = 3 }
+
+[profile.ci.junit]
+path = "junit.xml"
+
+# The integration binaries that shell out to a real terraphim_server
+# (TERRAPHIM_SERVER_BIN) are the only ones allowed a retry and a longer
+# slow-timeout, and only in CI: they wait on a live HTTP service. Everything
+# else must be deterministic; a flaky test is a bug, not a retry candidate.
+[[profile.ci.overrides]]
+filter = 'binary(/^(server_mode_tests|cross_mode_consistency_test|integration_tests|kg_ranking_integration_test)$/)'
+retries = 1
+slow-timeout = { period = "120s", terminate-after = 3 }

.gitea/workflows/native-ci.yml

@@ -1,25 +1,45 @@
 name: native-ci
+# V-model gate order (Refs #254): fast checks -> tests -> coverage/security ->
+# nightly UB gates. Kept in sync with .github/workflows/ci.yml; see
+# docs/ci-gap-analysis.md "Sync rule". Every step's first token must be on the
+# terraphim-gitea-runner allowlist (cargo, rustup, bash, test, ...); curl and
+# python are denied, so tools are provisioned with `cargo install`.
 on:
   push:
   workflow_dispatch:
 jobs:
-  build:
+  # Stage 1: fast checks (fmt, clippy, deny). Fails in seconds, not minutes.
+  check:
     runs-on: terraphim-native
     steps:
+      - run: rustup show active-toolchain
       - run: cargo fmt --all -- --check
       - run: cargo clippy --workspace --all-targets -- -D warnings
+      # #2171: enrichment feature is not covered by default-features clippy.
+      - run: cargo clippy -p terraphim_sessions --features enrichment -- -D warnings
+      # Supply chain: advisories, licences, bans, sources per deny.toml.
+      # cargo-deny is present on runner-5 only, so install idempotently.
+      - run: cargo install cargo-deny --locked --version 0.20.2
+      - run: cargo deny check
+  # Stage 2: build + full test gate against a real terraphim_server.
+  test:
+    needs: check
+    runs-on: terraphim-native
+    steps:
+      # #106: the terraphim_update signed-archive tests shell out to the
+      # `zipsign` binary on the host. It is installed at /usr/local/bin/zipsign
+      # on bigbox (see "Host Tooling" in gitea-infrastructure HANDOVER.md);
+      # runners carry their own CARGO_HOME and do not all have ~/.cargo/bin on
+      # PATH, so a user-local install is invisible to them. Fail fast with a
+      # pointer to the fix rather than 21 failing test targets.
+      - name: Check host tooling (zipsign)
+        # Note: the terraphim-gitea-runner command policy inspects the
+        # literal first token; `if`/`then`/`fi` shell keywords get rejected.
+        # Use `test` (the only conditional primitive on the allowlist) and
+        # `||` chaining instead. Refs #106.
+        run: |
+          test -x /usr/local/bin/zipsign && /usr/local/bin/zipsign --version || { echo "::error::zipsign not found on PATH. Install on the runner host: sudo install -m 0755 ~/.cargo/bin/zipsign /usr/local/bin/zipsign (see gitea-infrastructure HANDOVER.md, 'Host Tooling'). Refs #106"; exit 1; }
       - run: cargo build --workspace
-      # #84: broaden the workspace gate so integration tests, binary
-      # smoke tests, and example doctests participate in the gate. The
-      # narrower `--lib` gate silently skipped crates/terraphim_mcp_server
-      # tests/test_tools_list.rs and tests/test_all_mcp_tools.rs, which
-      # exercised real stdio/JSON-RPC round-trips against the
-      # terraphim_mcp_server binary. `--tests --bins --examples` adds
-      # those targets; `--lib` is kept so the existing crate-internal
-      # coverage is still exercised. `--no-fail-fast` makes all targets
-      # run even when one fails, so a single broken test does not hide
-      # the rest of the failures behind an early abort.
-      - run: cargo test --workspace --tests --bins --examples --lib --no-fail-fast
       # #113: build terraphim_server from terraphim-ai so the
       # server-binary-dependent integration tests have a real binary.
       # terraphim_server is not a workspace member here -- it lives in
@@ -41,22 +61,44 @@ jobs:
       # requirements (1.20.2) match both 1.20.2 and 1.21.0 in the registry
       # and cargo aborts with "patch resolved to more than one candidate".
       - run: cargo install --locked --git https://git.terraphim.cloud/terraphim/terraphim-ai --tag v1.21.3 --root /tmp/terraphim_server_install --config 'registries.terraphim.index="sparse+https://git.terraphim.cloud/api/packages/terraphim/cargo/"' --config 'registry.global-credential-providers=["cargo:token"]' --bin terraphim_server terraphim_server
-      # #113: run the integration tests that require a real
-      # terraphim_server binary. ensure_server_binary() (in
-      # cross_mode_consistency_test.rs / kg_ranking_integration_test.rs)
-      # and server_binary_path() (in integration_tests.rs) both resolve
-      # TERRAPHIM_SERVER_BIN first, so pointing the env var at the
-      # install root is enough.
-      - run: TERRAPHIM_SERVER_BIN=/tmp/terraphim_server_install/bin/terraphim_server cargo test -p terraphim_agent --test cross_mode_consistency_test -- --nocapture
-      - run: TERRAPHIM_SERVER_BIN=/tmp/terraphim_server_install/bin/terraphim_server cargo test -p terraphim_agent --test integration_tests -- --nocapture
-      - run: TERRAPHIM_SERVER_BIN=/tmp/terraphim_server_install/bin/terraphim_server cargo test -p terraphim_agent --test kg_ranking_integration_test -- --nocapture
-      # #2171: enrichment feature clippy + test invocations.
-      - run: cargo clippy -p terraphim_sessions --features enrichment -- -D warnings
-      - run: cargo test -p terraphim_sessions --features enrichment --lib --no-fail-fast
-      # #95: isolated packaged install-graph regression.
-      - run: cargo test -p terraphim_agent --test packaged_install_graph_regression -- --nocapture
-      # #118: repo guards -- duplicate-crate detection and the publish gate's own
-      # tests. Rust tests, not shell steps: the runner allowlist rejects any
-      # program that is not cargo ("policy rejected command: ... not on the
-      # allowlist"), which is what took CI down from #112 until now.
-      - run: cargo test -p terraphim_agent --test ci_guards -- --nocapture
+      # nextest: one binary per target, parallel scheduling, JUnit output
+      # (.config/nextest.toml profile ci). --all-targets keeps the
+      # terraphim-agents#91 coverage: binaries, examples and tests/*.rs.
+      - run: cargo install cargo-nextest --locked
+      - run: TERRAPHIM_SERVER_BIN=/tmp/terraphim_server_install/bin/terraphim_server cargo nextest run --workspace --all-targets --profile ci
+      # nextest does not run doctests.
+      - run: cargo test --workspace --doc --no-fail-fast
+      # #113: focused re-runs of the server-backed integration tests (also in
+      # the run above; kept for fast failure attribution).
+      - run: TERRAPHIM_SERVER_BIN=/tmp/terraphim_server_install/bin/terraphim_server cargo nextest run -p terraphim_agent --test cross_mode_consistency_test --test integration_tests --test kg_ranking_integration_test --profile ci
+      # #2171 / terraphim-clients#150: feature lanes invisible to default features.
+      - run: cargo nextest run -p terraphim_sessions --features enrichment --lib --profile ci
+      - run: cargo nextest run -p terraphim_sessions --all-features --profile ci
+      # #95 / #118: focused regression and repo guards (Rust tests, not shell
+      # steps: the runner allowlist rejects non-cargo programs).
+      - run: cargo nextest run -p terraphim_agent --test packaged_install_graph_regression --test ci_guards --profile ci
+  # Stage 3: coverage gate. Threshold only ever goes up (docs/ci-gap-analysis.md).
+  # --ignore-run-fail: the test job owns test failures; this job owns the
+  # percentage, so a red test must not hide the coverage number.
+  coverage:
+    needs: check
+    runs-on: terraphim-native
+    steps:
+      - run: rustup component add llvm-tools
+      - run: cargo install cargo-llvm-cov --locked
+      - run: cargo llvm-cov --workspace --lib --lcov --output-path lcov.info --ignore-run-fail
+      - run: cargo llvm-cov report --fail-under-lines 65
+  # Stage 4: UB gates on nightly (from the #252 UB_RUNBOOK). Miri covers the
+  # pure-computation crates only; tokio/reqwest paths are unsupported by Miri.
+  # terraphim_hooks' discovery tests spawn a process (posix_spawn), which Miri
+  # cannot emulate, and validation::tests::test_validate_latency runs 1000
+  # timed iterations that are meaningless (and very slow) under Miri, hence
+  # --skip discovery --skip latency.
+  ub-gates:
+    needs: check
+    runs-on: terraphim-native
+    steps:
+      - run: rustup toolchain install nightly --profile minimal -c miri -c rust-src
+      - run: cargo +nightly miri setup
+      - run: MIRIFLAGS="-Zmiri-disable-isolation" cargo +nightly miri test -p terraphim_negative_contribution -p terraphim_command_runtime -p terraphim_hooks --lib -- --skip discovery --skip latency
+      - run: MIRIFLAGS="-Zmiri-disable-isolation -Zmiri-tree-borrows" cargo +nightly miri test -p terraphim_negative_contribution -p terraphim_command_runtime -p terraphim_hooks --lib -- --skip discovery --skip latency

.github/workflows/ci.yml

@@ -1,4 +1,10 @@
 name: CI
+# Public mirror of .gitea/workflows/native-ci.yml (Refs #254). Same gate
+# order and the same cargo invocations; differences are limited to
+# provisioning (GitHub actions instead of cargo install on a self-hosted
+# runner), the multi-platform matrix, and the absence of the terraphim_server
+# backed integration lane, which needs the private registry. See
+# docs/ci-gap-analysis.md "Sync rule".
 on:
   push:
     branches: [main]
@@ -9,17 +15,105 @@ on:
 env:
   CARGO_TERM_COLOR: always
   RUST_BACKTRACE: 1
+  # The 1.21.x terraphim family resolves from the private Gitea registry
+  # (see [patch.crates-io] in Cargo.toml). Same secret release-binaries uses.
+  CARGO_REGISTRIES_TERRAPHIM_TOKEN: ${{ secrets.CARGO_REGISTRIES_TERRAPHIM_TOKEN }}
 
 jobs:
-  build:
+  # Stage 1: fast checks
+  check:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: dtolnay/rust-toolchain@stable
+      - uses: dtolnay/rust-toolchain@master
         with:
+          toolchain: 1.97.1
           components: rustfmt, clippy
       - uses: Swatinem/rust-cache@v2
       - run: cargo fmt --all -- --check
       - run: cargo clippy --workspace --all-targets -- -D warnings
+      - run: cargo clippy -p terraphim_sessions --features enrichment -- -D warnings
+      - uses: taiki-e/install-action@cargo-deny
+      - run: cargo deny check
+
+  # Stage 2: tests on every release platform
+  test:
+    needs: check
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@master
+        with:
+          toolchain: 1.97.1
+      - uses: Swatinem/rust-cache@v2
+      - uses: taiki-e/install-action@nextest
       - run: cargo build --workspace
-      - run: cargo test --workspace --lib --no-fail-fast
+      # Lib and doc tests on all platforms. Integration tests that need a
+      # terraphim_server binary run only on native-ci.
+      - run: cargo nextest run --workspace --lib --profile ci
+      - run: cargo test --workspace --doc --no-fail-fast
+      # #2171: enrichment-feature test invocation.
+      - run: cargo nextest run -p terraphim_sessions --features enrichment --lib --profile ci
+      # #4325: zero-chunk smoke for terraphim_grep default features.
+      - run: cargo nextest run -p terraphim_grep --test default_feature_smoke --profile ci
+      # #95: isolated packaged install-graph regression.
+      - run: cargo nextest run -p terraphim_agent --test packaged_install_graph_regression --profile ci
+
+  # Stage 3: coverage gate (Linux only; threshold only ever increases).
+  # --ignore-run-fail: the test job owns test failures; this job owns the number.
+  coverage:
+    needs: check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@master
+        with:
+          toolchain: 1.97.1
+          components: llvm-tools
+      - uses: Swatinem/rust-cache@v2
+      - uses: taiki-e/install-action@cargo-llvm-cov
+      - run: cargo llvm-cov --workspace --lib --lcov --output-path lcov.info --ignore-run-fail
+      - run: cargo llvm-cov report --fail-under-lines 65
+      - uses: actions/upload-artifact@v4
+        with:
+          name: lcov
+          path: lcov.info
+
+  # Stage 4: UB gates on nightly (from the #252 UB_RUNBOOK)
+  ub-gates:
+    needs: check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@nightly
+        with:
+          components: miri, rust-src
+      - uses: Swatinem/rust-cache@v2
+      - run: cargo +nightly miri setup
+      - run: MIRIFLAGS="-Zmiri-disable-isolation" cargo +nightly miri test -p terraphim_negative_contribution -p terraphim_command_runtime -p terraphim_hooks --lib -- --skip discovery --skip latency
+      - run: MIRIFLAGS="-Zmiri-disable-isolation -Zmiri-tree-borrows" cargo +nightly miri test -p terraphim_negative_contribution -p terraphim_command_runtime -p terraphim_hooks --lib -- --skip discovery --skip latency
+
+  # Stage 5: benchmark regression, informational on PRs (baselines from #253)
+  benchmarks:
+    if: github.event_name == 'pull_request'
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@master
+        with:
+          toolchain: 1.97.1
+      - uses: Swatinem/rust-cache@v2
+      - run: cargo bench -p terraphim_grep --features code-search --bench hybrid_search -- --output-format bencher | tee bench-output.txt
+      - uses: benchmark-action/github-action-benchmark@v1
+        with:
+          tool: cargo
+          output-file-path: bench-output.txt
+          alert-threshold: "120%"
+          comment-on-alert: true
+          fail-on-alert: false
+          auto-push: false

crates/terraphim-session-analyzer/src/analyzer.rs

@@ -55,7 +55,7 @@ impl Analyzer {
     ///
     /// Public API consumed only by cross-binary integration tests.
     /// Consumers: `tests/integration_tests.rs`.
-        #[must_use]
+    #[must_use]
     /// Public API consumed only by `tests/integration_tests.rs` (cross-binary integration test). The `tsa` binary does not call this method.
     #[allow(dead_code)]
     pub fn with_config(mut self, config: AnalyzerConfig) -> Self {
@@ -765,7 +765,7 @@ impl Analyzer {
     /// Public API consumed only by cross-binary integration tests
     /// (in-file unit tests in this module also exercise it directly).
     /// Consumers: `tests/integration_tests.rs` and lib unit tests in this file.
-        #[must_use]
+    #[must_use]
     /// Public API consumed only by lib unit tests in this file and `tests/integration_tests.rs` (cross-binary integration test). The `tsa` binary does not call this method.
     #[allow(dead_code)]
     pub fn detect_tool_chains(

crates/terraphim-session-analyzer/src/models.rs

@@ -134,7 +134,7 @@ impl ToolCategory {
     /// Public API consumed only by integration tests and downstream callers.
     /// The `tsa` binary does not call this method, hence the conditional allow.
     /// Consumers: `tests/integration_tests.rs` (cross-binary integration test).
-        #[must_use]
+    #[must_use]
     /// Public API consumed only by `tests/integration_tests.rs` (cross-binary integration test). The `tsa` binary does not call this method.
     #[allow(dead_code)]
     pub fn from_string(s: &str) -> Self {

crates/terraphim-session-analyzer/src/parser.rs

@@ -341,7 +341,7 @@ impl SessionParser {
     ///
     /// Public API consumed only by cross-binary integration tests.
     /// Consumers: `tests/integration_tests.rs`.
-        #[must_use]
+    #[must_use]
     /// Public API consumed only by `tests/integration_tests.rs` (cross-binary integration test). The `tsa` binary does not call this method.
     #[allow(dead_code)]
     pub fn entry_count(&self) -> usize {
@@ -358,7 +358,7 @@ impl SessionParser {
     ///
     /// Public API consumed only by cross-binary integration tests.
     /// Consumers: `tests/integration_tests.rs`.
-        #[must_use]
+    #[must_use]
     /// Public API consumed only by `tests/integration_tests.rs` (cross-binary integration test). The `tsa` binary does not call this method.
     #[allow(dead_code)]
     pub fn entries_in_window(
@@ -385,7 +385,7 @@ impl SessionParser {
     ///
     /// Public API consumed only by cross-binary integration tests.
     /// Consumers: `tests/integration_tests.rs`.
-        #[must_use]
+    #[must_use]
     /// Public API consumed only by `tests/integration_tests.rs` (cross-binary integration test). The `tsa` binary does not call this method.
     #[allow(dead_code)]
     pub fn get_agent_types(&self) -> Vec<String> {
@@ -404,7 +404,7 @@ impl SessionParser {
     ///
     /// Public API consumed only by cross-binary integration tests.
     /// Consumers: `tests/integration_tests.rs`.
-        #[must_use]
+    #[must_use]
     /// Public API consumed only by `tests/integration_tests.rs` (cross-binary integration test). The `tsa` binary does not call this method.
     #[allow(dead_code)]
     pub fn build_timeline(&self) -> Vec<TimelineEvent> {

crates/terraphim-session-analyzer/src/patterns/matcher.rs

@@ -33,7 +33,7 @@ pub trait PatternMatcher: Send + Sync {
     ///
     /// Trait method consumed only by in-file unit tests in this module.
     /// External callers don't currently use it, hence the conditional allow.
-        /// Trait method consumed only by in-file unit tests in this module. External callers do not currently invoke it.
+    /// Trait method consumed only by in-file unit tests in this module. External callers do not currently invoke it.
     #[allow(dead_code)]
     fn matcher_type(&self) -> &'static str;
 }

crates/terraphim_agent/src/client.rs

@@ -228,7 +228,6 @@ pub struct AutocompleteResponse {
 // does not enable `firecracker`, so the lint sees them as dead. See
 // `Cargo.toml` [features] for the firecracker declaration.
 
-
 #[derive(Debug, Serialize, Deserialize, Clone)]
 // Feature-gated to `firecracker`; see VM Management Types comment above.
 #[allow(dead_code)]
@@ -430,8 +429,6 @@ impl ApiClient {
         Ok(body)
     }
 
-
-
     // VM Management APIs
 
     // Feature-gated to `firecracker`; see VM Management Types comment above.