ci.yml

# Relavium CI — the green gate every push and PR must pass (Phase 0 · 0.G).
#
# Runs lint + typecheck + test across every workspace in dependency order with the
# Turborepo cache, plus the formatting check and the no-vendor-type-across-the-seam fence.
#
# Branch protection (set in the GitHub repo settings, not here): `ci` and `coverage` are the REQUIRED
# status checks to merge into `main`. Wire, usage, filesystem, secrets and packed CLI jobs feed `ci` through an explicit
# success-only aggregation; they cannot silently skip or fail while `ci` stays green. The other jobs
# self-label `(advisory)` — `floor-check`, `peer-dep-gate` and `windows-concurrency`.
#
# `coverage` enforces the testing.md >=90% line+branch floor for `@relavium/llm` and `@relavium/mcp` only.
# `packages/core` is measured and printed by the same run but does not fail it: its branch margin is +0.83
# (90.83 measured 2026-07-29) and Phase 2.5.5 Waves 1-3 edit `core` heavily, so blocking merges on a
# sub-1-point margin would red-CI real work for no defect. That is a scoped, dated ruling with a promotion
# trigger — Wave 3's test-coverage items — not an open-ended exemption. A local `pnpm coverage` still
# enforces all three, so the floor never silently relaxes for a developer.
#
# Caching: the always-on layer is the GitHub Actions `.turbo` cache (restored/saved below),
# which makes a no-change re-run a Turborepo cache hit — the M0 "demonstrably hitting"
# criterion. The Vercel-style Turborepo REMOTE cache (cross-runner sharing) is opt-in: add
# repo secrets `TURBO_TOKEN` and `TURBO_TEAM` and Turbo picks them up automatically below.
#
# Third-party actions are pinned to a full commit SHA (the `# vX.Y.Z` comment tracks the
# human-readable release) so a moved tag can't inject unreviewed code; bumps are deliberate.
#
# Install-script posture: `pnpm install` runs WITHOUT `--ignore-scripts` deliberately. Supply-chain risk is
# handled more precisely one level up, by `pnpm.onlyBuiltDependencies` in the root package.json, which
# allowlists the ONLY two packages permitted to run lifecycle scripts (`better-sqlite3` for its native
# prebuild, `esbuild` for its platform binary). Every other transitive dependency is already blocked.
# Passing `--ignore-scripts` here would break both of those and gain nothing — it is a weaker, blunter form
# of a control the repo already applies.
name: CI

on:
  push:
    branches: [main, development]
  pull_request:

# Cancel superseded runs so CI tracks the latest push — but never cancel a run on `main` (its
# history is the merge record and must complete). The group key: a PR run is keyed by its PR
# number (`github.event.number` — so two PRs open from the SAME head branch stay independent and
# can't cancel each other), a push run by its short branch (`ref_name`, e.g. `development`).
# `event_name` keeps a push and its same-SHA PR in separate groups (otherwise one run cancels the
# other and a cancelled required check can block merge): `ci-CI-push-development` vs
# `ci-CI-pull_request-10`.
concurrency:
  group: ci-${{ github.workflow }}-${{ github.event_name }}-${{ github.event.number || github.ref_name }}
  cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}

permissions:
  contents: read

env:
  # Picked up by Turbo for remote caching when the secrets are configured; harmless if empty.
  TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
  TURBO_TEAM: ${{ secrets.TURBO_TEAM }}

jobs:
  ci:
    needs: [wire-mutations, usage-mutations, fs-mutations, secrets-mutations, packed-cli]
    if: ${{ always() }}
    name: lint · typecheck · test
    runs-on: ubuntu-latest
    # A cold lint/typecheck plus serialized workspace run takes about 12.5 minutes, before
    # build, tool checks and the replay smoke's six sequential, individually bounded 45s workers.
    # Keep a finite outer watchdog without truncating those unchanged native/test bounds.
    timeout-minutes: 25
    steps:
      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
        with:
          persist-credentials: false
          # The offline replay check independently verifies frozen blobs against its actual predecessor commit.
          fetch-depth: 0

      - name: Set up pnpm
        # pnpm version comes from the root package.json `packageManager`.
        uses: pnpm/action-setup@fc06bc1257f339d1d5d8b3a19a8cae5388b55320 # v4.4.0

      - name: Set up Node
        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
        with:
          node-version-file: .nvmrc
          cache: pnpm

      - name: Require complete W8 causal acceptance jobs
        env:
          RELAVIUM_W8_JOB_RESULTS: ${{ toJSON(needs) }}
        run: node tools/ci/require-w8-acceptance.mjs

      - name: Require complete filesystem causal controls
        env:
          FS_CONTROLS_RESULT: ${{ needs.fs-mutations.result }}
        run: node -e "require('node:assert/strict').equal(process.env.FS_CONTROLS_RESULT, 'success')"

      - name: Require complete secrets causal controls
        env:
          SECRETS_CONTROLS_RESULT: ${{ needs.secrets-mutations.result }}
        run: node -e "require('node:assert/strict').equal(process.env.SECRETS_CONTROLS_RESULT, 'success')"

      - name: Require complete packed CLI controls
        env:
          PACKED_CLI_RESULT: ${{ needs.packed-cli.result }}
        run: node -e "require('node:assert/strict').equal(process.env.PACKED_CLI_RESULT, 'success')"

      # A squash/main-based checkout need not contain development's immutable predecessor object.
      # Fetch only this canonical pin during CI setup; the acceptance harness itself stays offline.
      - name: Ensure immutable replay predecessor is available
        shell: bash
        run: |
          BASELINE=$(node --input-type=module -e "import { baselineCommit } from './tools/budget-replay-compat/baseline-provenance.mjs'; process.stdout.write(baselineCommit)")
          if ! git --no-replace-objects cat-file -e "$BASELINE^{commit}"; then
            if ! git fetch --no-tags origin "$BASELINE"; then
              echo "::error::Immutable replay predecessor $BASELINE is unavailable from origin; restore that exact object before running the offline gate."
              exit 1
            fi
          fi
          git --no-replace-objects cat-file -e "$BASELINE^{commit}"

      - name: Install (frozen lockfile)
        run: pnpm install --frozen-lockfile

      - name: Restore Turborepo cache
        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
        with:
          path: .turbo
          key: turbo-${{ runner.os }}-${{ github.sha }}
          restore-keys: |
            turbo-${{ runner.os }}-

      - name: Initialize native DB scheduling diagnostics
        env:
          RELAVIUM_DB_NATIVE_DIAGNOSTICS: ${{ runner.temp }}/db-native-${{ github.run_id }}-${{ github.run_attempt }}/events.jsonl
        run: |
          node --input-type=module <<'NODE'
          import { mkdirSync, writeFileSync } from 'node:fs';
          import { dirname } from 'node:path';
          import { availableParallelism } from 'node:os';
          const destination = process.env.RELAVIUM_DB_NATIVE_DIAGNOSTICS;
          mkdirSync(dirname(destination), { recursive: true });
          writeFileSync(destination, JSON.stringify({
            stage: 'ci-invocation', node: process.version, platform: process.platform,
            arch: process.arch, availableParallelism: availableParallelism(),
            workspaceTestConcurrency: 1,
            expectedDbCache: 'miss: unique diagnostic path is hashed by DB test only',
            executionEvidence: 'parent and child records; this setup record alone is not execution'
          }) + '\n');
          NODE
          echo "RELAVIUM_DB_NATIVE_DIAGNOSTICS=$RELAVIUM_DB_NATIVE_DIAGNOSTICS" >> "$GITHUB_ENV"

      # Match local CI: finish lint/typecheck before one workspace test task at a time.
      # Every file/case and all native races inside each test retain their original bounds.
      - name: Lint, typecheck, test
        run: pnpm ci:workspaces
      # Setup/upload alone cannot prove native work executed or its children were joined.
      - name: Require native DB execution diagnostics
        run: node tools/ci/require-native-db-diagnostics.mjs
      - name: Preserve native DB scheduling diagnostics
        if: ${{ always() }}
        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
        with:
          name: db-native-${{ github.run_id }}-${{ github.run_attempt }}
          path: ${{ runner.temp }}/db-native-${{ github.run_id }}-${{ github.run_attempt }}
          retention-days: 7
          if-no-files-found: warn
      # Typecheck the root/tooling *.config.ts that sit outside every package's tsc program.
      - name: Typecheck tooling configs
        run: pnpm typecheck:tools
      # Not redundant with typecheck: `build` runs each package's emit (tsconfig.build.json
      # → dist), which `typecheck` (tsconfig.json --noEmit) does not — it catches
      # emit-only failures and proves the published artifact compiles.
      - name: Build
        run: pnpm turbo run build

      # Drift gate (2.L · ADR-0051): the published CLI bundle inlines the @relavium/* engine and externalizes
      # every third-party dep — its external import closure must equal the declared `dependencies`, or a global
      # `npm i -g relavium` would fail to resolve a missing dep. Needs the build above.
      - name: CLI bundle closure matches its declared dependencies
        run: pnpm lint:bundle-closure

      - name: Compiled CLI meta paths stay outside runtime services
        run: pnpm smoke:cli-bootstrap

      # Drift gate: the committed migration must match src/schema.ts. If a schema change
      # (or an upstream @relavium/shared enum change the CHECKs derive from) wasn't
      # regenerated via `pnpm --filter @relavium/db db:generate`, regenerating here produces
      # an uncommitted diff and fails — turning a silent stale-migration into a red check.
      - name: DB migration is in sync with the schema
        run: pnpm db:sync-check

      # Formatting is run, not argued (code-style-typescript.md). Via turbo so it caches.
      - name: Format check
        run: pnpm turbo run format:check

      # Prove the no-vendor-type-across-the-@relavium/llm-seam fence is live (0.F).
      - name: Seam fence is enforced
        run: pnpm lint:fence-check

      # The size half of the fence: engine packages' runtime dependency graphs must stay
      # within their reviewed allowlists (a new engine dep = an ADR + a deliberate edit to
      # tools/engine-deps/check.mjs in the same change).
      - name: Engine dependency allowlist
        run: pnpm lint:engine-deps

      # `tools/` is real code that gates real things (the seam fence, the bundle-closure guard, the
      # models.dev sync). The root `ci` script has always linted it; this job never did, so a lint error in
      # a guard script could merge while `pnpm run ci` was red locally (#312).
      # NB: it is `pnpm run ci`, never `pnpm ci` — pnpm reserves `ci` as a builtin and answers
      # `ERR_PNPM_CI_NOT_IMPLEMENTED`, so the script is unreachable by the name everyone types.
      - name: Lint the tooling scripts
        run: pnpm lint:tools

      # A repo-local SECOND checkout must never be collected by a root run (CR-90). This is the one check
      # whose defect CI could not have caught on its own: the leak lives in `.claude/worktrees/`, hidden by a
      # LOCAL `.git/info/exclude` entry, so a clean CI checkout never has it. The vitest exclusions defend a
      # developer's tree; this step is what stops them being weakened — without it the guard would be the only
      # root-`ci` check missing here, which is the #312 divergence the two steps above exist to close.
      - name: Test isolation (no repo-local checkout in the run)
        run: pnpm lint:test-isolation

      # RUN the artifact this job just built, through the SAME `pnpm smoke:cli` script the root `ci` script
      # calls — a check that exists in only one of the two is exactly the #312 divergence this change closes.
      # Until now nothing in the required gate executed
      # `apps/cli/dist/index.js` — only the advisory Windows leg and the tag-gated release smoke did (#294) —
      # so a bundle that builds but cannot boot merged green. The `run --json` leg additionally proves the
      # migrations resolve beside the bundle, which is the failure `apps/cli/drizzle/**` becoming a declared
      # turbo output (#315) exists to prevent: a cache-hit replay used to leave `dist/` fresh next to a
      # missing `drizzle/`, crashing on first DB touch with nothing red anywhere.
      - name: Smoke the compiled binary
        run: pnpm smoke:cli

      # ADR-0109 exact module identity must hold in actual artifacts, separately from source controls.
      - name: Smoke built workspace and bundled CLI media ownership (offline)
        run: pnpm smoke:media-packaging

      # The maintainer capture command handles real credentials and paid egress. Exercise its stdin/file/
      # cancellation boundary offline, through the same script as the local required gate.
      - name: Smoke the overflow capture command (offline)
        run: pnpm smoke:overflow-capture

      # Durable budget authorization must remain unreadable by the actual pre-W7 predecessor.
      # Keep the required GitHub gate aligned with the offline smoke in pnpm run ci (ADR-0100).
      - name: Smoke the budget replay compatibility harness (offline)
        run: pnpm smoke:budget-replay

  # Offline, uncached semantic removal/restoration evidence. Required indirectly through ci.needs.
  # ADR-0105 isolated, current-source removal/restoration evidence, required through ci.needs.
  fs-mutations:
    name: Wave 2 filesystem causal controls
    # ADR-0106/0109 extend the original 26 controls with complete media/lifetime workloads.
    # The 20-minute job historically reached only 46 of 93 controls; the later budget covered 99.
    # The current cohort is 110 controls (2026-10-15); this comment does not certify its execution.
    # Per-phase 90-second/test 15-second deadlines and output/evidence ceilings remain unchanged.
    timeout-minutes: 60
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
        with:
          persist-credentials: false
      - uses: pnpm/action-setup@fc06bc1257f339d1d5d8b3a19a8cae5388b55320 # v4.4.0
      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
        with:
          node-version-file: .nvmrc
          cache: pnpm
      - name: Install (frozen lockfile)
        run: pnpm install --frozen-lockfile
      - name: Verify causal outcome and worker lifecycle guards
        run: pnpm test:acceptance-tools
      - name: Run filesystem removal and restoration controls
        env:
          RELAVIUM_ACCEPTANCE_EVIDENCE: ${{ runner.temp }}/wave2-acceptance
        run: pnpm check:fs-mutations
      - name: Retain bounded filesystem control metadata
        if: ${{ always() }}
        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
        with:
          name: wave2-filesystem-${{ github.run_id }}-${{ github.run_attempt }}
          path: ${{ runner.temp }}/wave2-acceptance/filesystem
          if-no-files-found: warn
          retention-days: 7

  secrets-mutations:
    name: Wave 2 secrets causal controls
    # The historical 35-control, three-phase capture exceeded the former aggregate budget.
    # The current cohort is 57 controls (2026-10-18); this comment does not certify its execution.
    # Per-phase, case/hook, output and retained-evidence bounds remain unchanged.
    timeout-minutes: 30
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
        with:
          persist-credentials: false
      - uses: pnpm/action-setup@fc06bc1257f339d1d5d8b3a19a8cae5388b55320 # v4.4.0
      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
        with:
          node-version-file: .nvmrc
          cache: pnpm
      - name: Install (frozen lockfile)
        run: pnpm install --frozen-lockfile
      - name: Verify causal outcome and worker lifecycle guards
        run: pnpm test:acceptance-tools
      - name: Run secrets removal and restoration controls
        env:
          RELAVIUM_ACCEPTANCE_EVIDENCE: ${{ runner.temp }}/wave2-acceptance
        run: pnpm check:secrets-mutations
      - name: Retain bounded secrets control metadata
        if: ${{ always() }}
        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
        with:
          name: wave2-secrets-${{ github.run_id }}-${{ github.run_attempt }}
          path: ${{ runner.temp }}/wave2-acceptance/secrets
          if-no-files-found: warn
          retention-days: 7

  wire-mutations:
    name: W8 wire causal acceptance
    timeout-minutes: 10
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
        with:
          persist-credentials: false
          fetch-depth: 0
      - uses: pnpm/action-setup@fc06bc1257f339d1d5d8b3a19a8cae5388b55320 # v4.4.0
      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
        with:
          node-version-file: .nvmrc
          cache: pnpm
      - name: Install (frozen lockfile)
        run: pnpm install --frozen-lockfile
      - name: Build workspaces
        run: pnpm turbo run build
      - name: Verify acceptance orchestration guards
        run: pnpm test:acceptance-tools
      - name: Run complete wire removal and restoration controls
        env:
          RELAVIUM_ACCEPTANCE_EVIDENCE: ${{ runner.temp }}/w8-acceptance
        run: pnpm check:wire-mutations
      - name: Retain bounded wire control metadata
        if: ${{ always() }}
        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
        with:
          name: w8-wire-${{ github.run_id }}-${{ github.run_attempt }}
          path: ${{ runner.temp }}/w8-acceptance/wire
          if-no-files-found: warn
          retention-days: 7

  # Offline, uncached semantic removal/restoration evidence. Required indirectly through ci.needs.
  usage-mutations:
    name: W8 usage causal acceptance
    timeout-minutes: 60
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
        with:
          persist-credentials: false
          fetch-depth: 0
      - uses: pnpm/action-setup@fc06bc1257f339d1d5d8b3a19a8cae5388b55320 # v4.4.0
      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
        with:
          node-version-file: .nvmrc
          cache: pnpm
      # A squash/main-based checkout need not contain development's immutable predecessor object.
      # Fetch only this canonical pin during CI setup; the acceptance harness itself stays offline.
      - name: Ensure immutable replay predecessor is available
        shell: bash
        run: |
          BASELINE=$(node --input-type=module -e "import { baselineCommit } from './tools/budget-replay-compat/baseline-provenance.mjs'; process.stdout.write(baselineCommit)")
          if ! git --no-replace-objects cat-file -e "$BASELINE^{commit}"; then
            if ! git fetch --no-tags origin "$BASELINE"; then
              echo "::error::Immutable replay predecessor $BASELINE is unavailable from origin; restore that exact object before running the offline gate."
              exit 1
            fi
          fi
          git --no-replace-objects cat-file -e "$BASELINE^{commit}"

      - name: Install (frozen lockfile)
        run: pnpm install --frozen-lockfile
      - name: Build workspaces
        run: pnpm turbo run build
      - name: Verify acceptance orchestration guards
        run: pnpm test:acceptance-tools
      - name: Run complete usage removal and restoration controls
        env:
          RELAVIUM_ACCEPTANCE_EVIDENCE: ${{ runner.temp }}/w8-acceptance
        run: pnpm check:usage-mutations
      - name: Retain bounded usage control metadata
        if: ${{ always() }}
        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
        with:
          name: w8-usage-${{ github.run_id }}-${{ github.run_attempt }}
          path: ${{ runner.temp }}/w8-acceptance/usage
          if-no-files-found: warn
          retention-days: 7

  # Supported-floor gate (ADR-0067). TWO floors, deliberately different:
  #   * the PUBLISHED floor is `apps/cli` `engines.node` = `>=22` — the max constraint in the CLI's RUNTIME
  #     dependency closure (`ink@7` / `cli-truncate` / `slice-ansi` → `>=22`); nothing runtime needs more.
  #   * the DEV-INSTALL floor is the root `engines.node` = `>=22.13.0` — forced ONLY by devDependencies
  #     (`vite` via vitest → `>=22.12.0`; `eslint-visitor-keys` via eslint → `^22.13.0`). `.npmrc` sets
  #     `engine-strict=true`, so `pnpm install` on the whole workspace HARD-FAILS below it.
  # A workspace install therefore cannot run at 22.0.0, so this leg pins the LOWEST Node the repo installs
  # on (22.13.0). It still exercises the published 22 line end-to-end and proves better-sqlite3 resolves its
  # Node-22 prebuild (ABI 127 — one binary for ALL of 22.x, so 22.13.0 loads the same artifact 22.0.0 would;
  # no node-gyp C++ source build). What it does NOT prove is that no RUNTIME dep requires >22.0.0 — that is
  # a property of the prod closure, verified at the ADR (see ADR-0067's amendment note) rather than here.
  # A SEPARATE job (the required check stays the ubuntu `ci` job on Node 24); promote once confirmed stable.
  floor-check:
    name: node 22-line floor (22.13.0) · typecheck · test · build (advisory)
    runs-on: ubuntu-latest
    # The complete serialized compatibility suite includes native DB waits; the former
    # fifteen-minute budget expired before CLI completion. Per-case limits stay unchanged.
    timeout-minutes: 25
    # Fully isolate this job from the shared Turbo remote cache. Turbo's task hash does NOT include the
    # runtime Node version, so floor-check (Node 22) and the required `ci` job (Node 24) share a hash —
    # either could replay the other's cached result and mask a version-specific failure. `--force` (below)
    # stops floor-check READING the shared cache; blanking the inherited workflow-level tokens here stops it
    # WRITING into it, so the required `ci` job can never replay a Node-22 result as Node-24-proven.
    env:
      TURBO_TOKEN: ''
      TURBO_TEAM: ''
    steps:
      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
        with:
          persist-credentials: false
      - uses: pnpm/action-setup@fc06bc1257f339d1d5d8b3a19a8cae5388b55320 # v4.4.0
      - name: Set up Node (the lowest 22.x the workspace installs on)
        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
        with:
          node-version: 22.13.0
          cache: pnpm
      - name: Install (frozen lockfile — better-sqlite3 must resolve a prebuild, not source-build)
        run: pnpm install --frozen-lockfile
      - name: Typecheck, test, build on the exact floor
        # `--force` = no cache READ (genuine Node-22 run, not a Node-24 replay); the job-level blanked
        # TURBO_TOKEN/TURBO_TEAM above = no cache WRITE (so `ci` never replays this Node-22 result). Both are
        # needed — see the job-level comment.
        # In this compatibility job, serialize file workers as well as workspaces
        # so unrelated files cannot consume the admitted-size cases' unchanged elapsed-time budget.
        # Every case still runs, including its explicit native concurrency. Required CI retains its
        # ordinary file workers; this job verifies the exact older runtime rather than cross-file load.
        run: |
          pnpm turbo run typecheck --force
          pnpm turbo run test --concurrency=1 --force -- --maxWorkers=1
          pnpm turbo run build --force

  # CI-only strict peer-dependency gate (.npmrc keeps this OFF for local installs so fresh
  # checkouts resolve while the surface packages' peers are not all in the tree yet). Catch
  # peer drift here without breaking local dev.
  peer-dep-gate:
    name: strict peer-dependency check (advisory)
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
        with:
          persist-credentials: false
      - uses: pnpm/action-setup@fc06bc1257f339d1d5d8b3a19a8cae5388b55320 # v4.4.0
      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
        with:
          node-version-file: .nvmrc
          cache: pnpm
      - name: Install with strict peers
        run: pnpm install --frozen-lockfile --config.strict-peer-dependencies=true

  # Engine coverage floor (testing.md >=90% line+branch, exit criterion #5). A REQUIRED check named
  # `engine coverage floor (llm, mcp)` — kept as a SEPARATE job from `ci` so a coverage regression is
  # legible on its own line rather than buried in a 12-step job. It is a repo-ROOT vitest run, which is what
  # makes the root-relative per-glob thresholds authoritative (vitest.config.ts). `packages/core` is measured
  # but not enforced here; see the header for the ruling and its promotion trigger.
  coverage:
    name: engine coverage floor (llm, mcp)
    runs-on: ubuntu-latest
    # One file worker isolates unchanged admitted-size case budgets from instrumentation
    # contention. A measured 1,481-second complete run plus setup exhausted 25 minutes;
    # reserve finite whole-suite headroom without changing case bounds or coverage thresholds.
    timeout-minutes: 30
    steps:
      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
        with:
          persist-credentials: false
      - uses: pnpm/action-setup@fc06bc1257f339d1d5d8b3a19a8cae5388b55320 # v4.4.0
      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
        with:
          node-version-file: .nvmrc
          cache: pnpm
      - name: Install (frozen lockfile)
        run: pnpm install --frozen-lockfile
      # Share the same Turborepo local cache the `ci` job writes, so the build below is a warm cache hit
      # on a same-SHA / recent-ancestor run rather than a cold rebuild.
      - name: Restore Turborepo cache
        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
        with:
          path: .turbo
          key: turbo-${{ runner.os }}-${{ github.sha }}
          restore-keys: |
            turbo-${{ runner.os }}-
      # `pnpm coverage` is a repo-ROOT vitest run (not a turbo task), so it does NOT get the `test`
      # task's `^build` — yet the `@relavium/*` package `exports` resolve only to `dist`. Build first so a
      # fresh checkout can resolve the cross-package entries (a per-package test gets dist via turbo `^build`;
      # each package still covers its OWN src via relative imports, so the floor stays src-accurate).
      - name: Build workspaces (so coverage resolves the @relavium/* package entries)
        run: pnpm turbo run build
      # ENFORCED subset only: `llm` and `mcp` fail the build below 90% line+branch. `core` is measured and
      # printed by the same run but does NOT fail it — its branch margin is +0.83 today and Phase 2.5.5
      # Waves 1-3 edit it heavily, so blocking on a sub-1-point margin would red-CI real work for no
      # defect (maintainer ruling 2026-07-29). A bare `pnpm coverage` still enforces all three locally.
      # Promote `core` here once Wave 3's test-coverage items land.
      - name: Engine coverage floor (>=90% line+branch — llm, mcp enforced; core measured)
        run: pnpm coverage:enforced

  # Cross-OS concurrency + headless gate (2.5.I S6). The DB write-path hardening (BEGIN IMMEDIATE + the
  # SQLITE_BUSY retry's Atomics.wait sleep + WAL locking) and the two-process concurrency e2e (a child spawn +
  # a file:// import of the built @relavium/db) are the parts most likely to behave differently on Windows —
  # ci.yml ran ubuntu-only (release.yml already smokes the built binary cross-OS, but never the test suite).
  # Runs the @relavium/db concurrency suite (the real Windows native-addon + WAL exercise) + the CLI
  # concurrency/perf harness there, the native Step 2 filesystem boundaries (ADR-0105), plus a headless
  # no-TTY smoke. Native links/containment complement portable Windows lexical vectors; these results are
  # evidence only after this job actually runs. A SEPARATE, advisory job (the required check
  # stays the ubuntu `ci` job) — promote to required in branch protection once confirmed stable. POSIX 0600/0700
  # perm assertions are NOT exercised here (a documented Windows no-op — ADR-0050); nor is ink's raw-mode code,
  # which is TTY-gated (the driver-selection gate picks the plain driver without a TTY — see the smoke below).
  windows-concurrency:
    name: windows · db concurrency + filesystem + headless smoke (advisory)
    runs-on: windows-latest
    timeout-minutes: 25
    steps:
      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
        with:
          persist-credentials: false
      - uses: pnpm/action-setup@fc06bc1257f339d1d5d8b3a19a8cae5388b55320 # v4.4.0
      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
        with:
          node-version-file: .nvmrc
          cache: pnpm
      - name: Install (frozen lockfile)
        run: pnpm install --frozen-lockfile
      - name: Restore Turborepo cache
        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
        with:
          path: .turbo
          key: turbo-${{ runner.os }}-${{ github.sha }}
          restore-keys: |
            turbo-${{ runner.os }}-
      # The two-process concurrency e2e spawns children that import the BUILT @relavium/db (by file:// URL),
      # so the dist must exist before the tests run.
      - name: Build
        id: windows-build
        run: pnpm turbo run build
      # These checks are independent after build. Retain every native result even if an earlier
      # suite fails; the job still fails on any failure (no continue-on-error or skipped gate).
      - name: DB concurrency suite (BEGIN IMMEDIATE + SQLITE_BUSY retry + WAL behave identically on Windows)
        if: ${{ !cancelled() && steps.windows-build.outcome == 'success' }}
        run: pnpm --filter @relavium/db test
      - name: CLI concurrency + query-shape harness (cross-process spawn + EXPLAIN plans on Windows)
        if: ${{ !cancelled() && steps.windows-build.outcome == 'success' }}
        run: pnpm --filter relavium exec vitest run concurrency perf-budget session-chain
      - name: Native CLI filesystem admission, containment, catalog and config (ADR-0105)
        if: ${{ !cancelled() && steps.windows-build.outcome == 'success' }}
        run: pnpm --filter relavium exec vitest run --no-file-parallelism --maxWorkers=1 src/config/paths.test.ts src/engine/tool-host/fs-policy.test.ts src/engine/tool-host/fs-policy-native-paths.test.ts src/engine/tool-host/fs-ancestor-consumers.test.ts src/engine/tool-host/fs.test.ts src/commands/fs-invocation.test.ts src/commands/fs-workspace-admission.test.ts src/workflows/catalog.test.ts src/config/resolve.test.ts src/engine/tool-host/fs-policy-scratch-composition.test.ts src/engine/tool-host/fs-rooted-glob.test.ts src/engine/tool-host/fs-write-floor-contract.test.ts
      - name: Native CAS and save_to containment (ADR-0105)
        if: ${{ !cancelled() && steps.windows-build.outcome == 'success' }}
        run: pnpm --filter @relavium/db exec vitest run src/media-store-paths.test.ts src/media-store-concurrency.test.ts src/media-store-read-races.test.ts src/media-store-entry-snapshots.test.ts src/media-store-publication-contention.test.ts src/media-store.test.ts src/media-write.test.ts
      - name: Shared filesystem ancestor algorithm and selector schema (ADR-0105)
        if: ${{ !cancelled() && steps.windows-build.outcome == 'success' }}
        run: pnpm --filter @relavium/shared exec vitest run src/existing-ancestor.test.ts src/config.test.ts
      - name: Shared media byte verification and publication (ADR-0106)
        if: ${{ !cancelled() && steps.windows-build.outcome == 'success' }}
        run: pnpm --filter @relavium/shared exec vitest run src/media-admission.test.ts src/media-deinline.test.ts src/media-deinline-lifecycle.test.ts src/media-iterator.test.ts src/media-publication.test.ts src/media-verifier.test.ts src/media-verifier-invalid.test.ts src/media-verifier-variants.test.ts src/media-verifier-identity.test.ts src/media-generated-result.test.ts src/media-verifier-vorbis.test.ts src/media-verifier-box-size.test.ts src/media-verifier-opus.test.ts src/media-verifier-flac.test.ts
      - name: Built workspace and bundled CLI native media ownership (ADR-0109)
        if: ${{ !cancelled() && steps.windows-build.outcome == 'success' }}
        run: pnpm smoke:media-packaging
      - name: Native CLI media publication and offline temporary maintenance (ADR-0106)
        if: ${{ !cancelled() && steps.windows-build.outcome == 'success' }}
        run: pnpm --filter relavium exec vitest run src/engine/media-paid-publication.test.ts src/engine/media-provider-admission.test.ts src/engine/media-publication.e2e.test.ts src/engine/media-retention-ack.test.ts src/engine/media-gc.test.ts src/engine/media-gc-delete-races.test.ts src/run-media-prune.test.ts src/engine/media-generated-publication.test.ts
      - name: Headless no-TTY smoke (the bundle loads; a piped chat picks the plain driver and exits cleanly)
        if: ${{ !cancelled() && steps.windows-build.outcome == 'success' }}
        shell: bash
        run: |
          set -euo pipefail
          node apps/cli/dist/index.js --help >/dev/null # the tsup bundle loads + --help renders
          # `chat` is TTY-gated on STDOUT (selectChatDriver / io.stdoutIsTty): with stdout captured (non-TTY)
          # here, the driver-selection gate picks the PLAIN driver (ink/setRawMode is never entered), and the
          # plain driver must exit cleanly on EOF — never crash. A regression routing to ink without a TTY would
          # throw "Raw mode is not supported…", which this catches.
          if out="$(printf '' | node apps/cli/dist/index.js chat 2>&1)"; then
            chat_status=0
          else
            chat_status=$?
          fi
          if [[ "$chat_status" -ne 4 ]]; then
            echo "::error::headless chat exited $chat_status (expected 4 on EOF)"; exit 1
          fi
          if printf '%s' "$out" | grep -qiE 'setRawMode|raw mode'; then
            echo "::error::chat entered raw mode without a TTY (the driver-selection gate regressed)"; exit 1
          fi
          echo "✓ windows headless no-TTY smoke passed"

  # Required exact-artifact controls are independent of the cached workspace build above.
  pack-cli:
    outputs:
      artifact-name: relavium-tarball-${{ github.run_id }}-${{ github.run_attempt }}
    name: build once and inspect the packed CLI
    runs-on: ubuntu-latest
    timeout-minutes: 20
    permissions:
      contents: read
    env:
      TURBO_TOKEN: ''
      TURBO_TEAM: ''
    steps:
      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
        with:
          persist-credentials: false
      - name: Set up pnpm
        uses: pnpm/action-setup@fc06bc1257f339d1d5d8b3a19a8cae5388b55320 # v4.4.0
      - name: Set up Node
        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
        with:
          node-version-file: .nvmrc
      - name: Install (frozen lockfile)
        run: pnpm install --frozen-lockfile
      # The runner builds inlined dependencies fresh, then prepack performs the sole final CLI build.
      - name: Pack once and independently inspect the public package
        env:
          RELAVIUM_PACKAGE_SOURCE_SHA: ${{ github.sha }}
        run: node tools/cli-package/pack.mjs "${{ runner.temp }}/packed-cli-artifact"
      - name: Upload the public tarball and package-test receipt
        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
        with:
          name: relavium-tarball-${{ github.run_id }}-${{ github.run_attempt }}
          path: |
            ${{ runner.temp }}/packed-cli-artifact/*.tgz
            ${{ runner.temp }}/packed-cli-artifact/package-test-receipt.json
          retention-days: 7
          if-no-files-found: error

  packed-cli-consumer:
    name: installed CLI (${{ matrix.id }})
    needs: pack-cli
    strategy:
      fail-fast: false
      matrix:
        include:
          - id: current-linux
            os: ubuntu-latest
            node: '24'
          - id: current-macos
            os: macos-latest
            node: '24'
          - id: current-windows
            os: windows-latest
            node: '24'
          - id: minimum-linux
            os: ubuntu-latest
            node: '22.0.0'
    runs-on: ${{ matrix.os }}
    timeout-minutes: 20
    permissions:
      contents: read
    env:
      TURBO_TOKEN: ''
      TURBO_TEAM: ''
    steps:
      # Only the test runner and fixtures use this checkout. No workspace dependencies or build.
      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
        with:
          persist-credentials: false
      # An explicit version avoids evaluating the workspace's >=22.13 install floor on Node 22.0.0.
      - name: Set up pnpm for the external consumer
        uses: pnpm/action-setup@fc06bc1257f339d1d5d8b3a19a8cae5388b55320 # v4.4.0
        with:
          version: 9.12.3
          run_install: false
      - name: Set up consumer Node
        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
        with:
          node-version: ${{ matrix.node == '22.0.0' && matrix.node || '' }}
          node-version-file: ${{ matrix.node != '22.0.0' && '.nvmrc' || '' }}
      - name: Download the exact packed CLI
        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
        with:
          name: ${{ needs.pack-cli.outputs.artifact-name }}
          path: ${{ runner.temp }}/packed-cli-artifact
      - name: Install outside the workspace and exercise the actual package
        env:
          RELAVIUM_PACKAGE_LEG: ${{ matrix.id }}
          RELAVIUM_PACKAGE_SOURCE_SHA: ${{ github.sha }}
        run: node tools/cli-package/consume.mjs "${{ runner.temp }}/packed-cli-artifact" "${{ runner.temp }}/packed-cli-report"
      - name: Upload successful installed-package receipt
        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
        with:
          name: ${{ needs.pack-cli.outputs.artifact-name }}-report-${{ matrix.id }}
          # A retried consumer replaces only its smoke receipt for the same immutable tarball.
          overwrite: true
          path: ${{ runner.temp }}/packed-cli-report/installed-consumer.json
          retention-days: 7
          if-no-files-found: error

  packed-cli:
    outputs:
      artifact-name: ${{ needs.pack-cli.outputs.artifact-name }}
    name: require all installed CLI consumers
    needs: [pack-cli, packed-cli-consumer]
    if: ${{ always() }}
    runs-on: ubuntu-latest
    timeout-minutes: 5
    permissions:
      contents: read
    env:
      TURBO_TOKEN: ''
      TURBO_TEAM: ''
    steps:
      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
        with:
          persist-credentials: false
      - name: Set up Node
        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
        with:
          node-version-file: .nvmrc
      - name: Require successful pack and every consumer before artifact downloads
        env:
          RELAVIUM_PACKAGE_JOB_RESULTS: ${{ toJSON(needs) }}
        run: node --input-type=module -e "import { requirePackageJobResults } from './tools/cli-package/binding.mjs'; requirePackageJobResults(JSON.parse(process.env.RELAVIUM_PACKAGE_JOB_RESULTS ?? 'null'));"
      - name: Download the exact packed CLI
        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
        with:
          name: ${{ needs.pack-cli.outputs.artifact-name }}
          path: ${{ runner.temp }}/packed-cli-artifact
      - name: Download all installed-package receipts
        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
        with:
          pattern: ${{ needs.pack-cli.outputs.artifact-name }}-report-*
          path: ${{ runner.temp }}/packed-cli-reports
          merge-multiple: false
      - name: Require pack and every consumer outcome and matching receipt
        env:
          RELAVIUM_PACKAGE_JOB_RESULTS: ${{ toJSON(needs) }}
          RELAVIUM_PACKAGE_SOURCE_SHA: ${{ github.sha }}
        run: node tools/cli-package/aggregate.mjs "${{ runner.temp }}/packed-cli-artifact" "${{ runner.temp }}/packed-cli-reports"