name: CI

on:
  push:
    branches: [main, master]
  pull_request:
  workflow_dispatch:
    inputs:
      suite:
        description: Manual CI suite to run
        required: true
        default: serial-reference
        type: choice
        options:
          - serial-reference
          - larger-runner-benchmark
          - consolidated-runner-benchmark
          - sharded-reference
          - optimized-larger-runners

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

permissions:
  contents: read

env:
  PRIMARY_NODE_VERSION: '24'

jobs:
  node-24-sharded:
    if: github.event_name == 'workflow_dispatch' && inputs.suite == 'sharded-reference'
    runs-on: ${{ startsWith(matrix.lane, 'snapshot-') && 'dsh-ubuntu-24-04-8core' || 'dsh-ubuntu-24-04-4core' }}
    name: node 24 / ${{ matrix.lane }}
    env:
      DSH_GATE_CONCURRENCY: ${{ matrix.gate_concurrency }}
      DSH_PUBLINT_CONCURRENCY: ${{ matrix.publint_concurrency }}
      DSH_ARTIFACT_SHARD: ${{ matrix.artifact_shard }}
      DSH_COVERAGE_MAX_WORKERS: ${{ matrix.coverage_max_workers }}
      DSH_COVERAGE_SHARD: ${{ matrix.coverage_shard }}
      DSH_LINT_SHARD: ${{ matrix.lint_shard }}
      DSH_SNAPSHOT_LANE: ${{ matrix.snapshot_lane }}
      DSH_STATIC_SHARD: ${{ matrix.static_shard }}
      DSH_SNAPSHOT_MAX_CONCURRENCY: ${{ matrix.snapshot_max_concurrency }}
      DSH_SNAPSHOT_PREBUILT: ${{ matrix.snapshot_prebuilt }}
      DSH_ESLINT_CACHE: ${{ matrix.eslint_cache }}
    strategy:
      fail-fast: false
      matrix:
        include:
          - lane: static-foundation-projection
            command: pnpm run check:ci:static
            gate_concurrency: '4'
            static_shard: 'foundation,site-projection'
          - lane: static-doc-types
            command: pnpm run check:ci:static
            gate_concurrency: '1'
            static_shard: doc-types
          - lane: static-api-contracts
            command: pnpm run check:ci:static
            gate_concurrency: '4'
            static_shard: api-contracts
          - lane: static-catalogs
            command: pnpm run check:ci:static
            gate_concurrency: '4'
            static_shard: catalogs
          - lane: static-prose
            command: pnpm run check:ci:static
            gate_concurrency: '4'
            static_shard: prose
          - lane: static-site-mpa
            command: pnpm run check:ci:static
            gate_concurrency: '1'
            static_shard: site-build
          - lane: typecheck
            command: pnpm run typecheck
          - lane: lint-package-sources-a-c
            command: pnpm run check:ci:lint
            gate_concurrency: '1'
            eslint_cache: '1'
            lint_shard: package-sources-a-c
          - lane: lint-package-sources-d-m
            command: pnpm run check:ci:lint
            gate_concurrency: '1'
            eslint_cache: '1'
            lint_shard: package-sources-d-m
          - lane: lint-package-sources-n-s
            command: pnpm run check:ci:lint
            gate_concurrency: '1'
            eslint_cache: '1'
            lint_shard: package-sources-n-s
          - lane: lint-package-sources-t-z
            command: pnpm run check:ci:lint
            gate_concurrency: '1'
            eslint_cache: '1'
            lint_shard: package-sources-t-z
          - lane: lint-package-tests-a-c
            command: pnpm run check:ci:lint
            gate_concurrency: '1'
            eslint_cache: '1'
            lint_shard: package-tests-a-c
          - lane: lint-package-tests-d-m
            command: pnpm run check:ci:lint
            gate_concurrency: '1'
            eslint_cache: '1'
            lint_shard: package-tests-d-m
          - lane: lint-package-tests-n-s
            command: pnpm run check:ci:lint
            gate_concurrency: '1'
            eslint_cache: '1'
            lint_shard: package-tests-n-s
          - lane: lint-package-tests-t-z
            command: pnpm run check:ci:lint
            gate_concurrency: '1'
            eslint_cache: '1'
            lint_shard: package-tests-t-z
          - lane: lint-repository
            command: pnpm run check:ci:lint
            gate_concurrency: '1'
            eslint_cache: '1'
            lint_shard: repository
          - lane: coverage-core-loop
            command: pnpm run check:ci:coverage
            gate_concurrency: '1'
            coverage_max_workers: '4'
            coverage_shard: core-loop
          - lane: coverage-state-session
            command: pnpm run check:ci:coverage
            gate_concurrency: '1'
            coverage_max_workers: '4'
            coverage_shard: state-session
          - lane: coverage-session-title
            command: pnpm run check:ci:coverage
            gate_concurrency: '1'
            coverage_max_workers: '4'
            coverage_shard: session-title
          - lane: coverage-models
            command: pnpm run check:ci:coverage
            gate_concurrency: '1'
            coverage_max_workers: '4'
            coverage_shard: models
          - lane: coverage-integrations
            command: pnpm run check:ci:coverage
            gate_concurrency: '1'
            coverage_max_workers: '4'
            coverage_shard: integrations
          - lane: coverage-sdk-capabilities
            command: pnpm run check:ci:coverage
            gate_concurrency: '1'
            coverage_max_workers: '4'
            coverage_shard: sdk-capabilities
          - lane: coverage-interfaces
            command: pnpm run check:ci:coverage
            gate_concurrency: '1'
            coverage_max_workers: '4'
            coverage_shard: interfaces
          - lane: coverage-execution
            command: pnpm run check:ci:coverage
            gate_concurrency: '1'
            coverage_max_workers: '4'
            coverage_shard: execution
          - lane: coverage-workflow
            command: pnpm run check:ci:coverage
            gate_concurrency: '1'
            coverage_max_workers: '4'
            coverage_shard: workflow
          - lane: coverage-workflow-worker
            command: pnpm run check:ci:coverage
            gate_concurrency: '1'
            coverage_max_workers: '4'
            coverage_shard: workflow-worker
          - lane: coverage-delegation
            command: pnpm run check:ci:coverage
            gate_concurrency: '1'
            coverage_max_workers: '4'
            coverage_shard: delegation
          - lane: coverage-repository
            command: pnpm run check:ci:coverage
            gate_concurrency: '1'
            coverage_max_workers: '4'
            coverage_shard: repository
          - lane: snapshot-support
            command: pnpm run check:ci:snapshot
            gate_concurrency: '1'
            snapshot_lane: support
            snapshot_max_concurrency: '5'
            snapshot_prebuilt: '1'
          - lane: snapshot-agents
            command: pnpm run check:ci:snapshot
            gate_concurrency: '1'
            snapshot_lane: agents
            snapshot_max_concurrency: '5'
            snapshot_prebuilt: '1'
          - lane: snapshot-acp-1
            command: pnpm run check:ci:snapshot
            gate_concurrency: '1'
            snapshot_lane: acp-1
            snapshot_max_concurrency: '5'
            snapshot_prebuilt: '1'
          - lane: snapshot-acp-2
            command: pnpm run check:ci:snapshot
            gate_concurrency: '1'
            snapshot_lane: acp-2
            snapshot_max_concurrency: '5'
            snapshot_prebuilt: '1'
          - lane: snapshot-acp-3
            command: pnpm run check:ci:snapshot
            gate_concurrency: '1'
            snapshot_lane: acp-3
            snapshot_max_concurrency: '5'
            snapshot_prebuilt: '1'
          - lane: snapshot-acp-4
            command: pnpm run check:ci:snapshot
            gate_concurrency: '1'
            snapshot_lane: acp-4
            snapshot_max_concurrency: '5'
            snapshot_prebuilt: '1'
          - lane: snapshot-acp-5
            command: pnpm run check:ci:snapshot
            gate_concurrency: '1'
            snapshot_lane: acp-5
            snapshot_max_concurrency: '5'
            snapshot_prebuilt: '1'
          - lane: snapshot-acp-6
            command: pnpm run check:ci:snapshot
            gate_concurrency: '1'
            snapshot_lane: acp-6
            snapshot_max_concurrency: '5'
            snapshot_prebuilt: '1'
          - lane: snapshot-acp-7
            command: pnpm run check:ci:snapshot
            gate_concurrency: '1'
            snapshot_lane: acp-7
            snapshot_max_concurrency: '5'
            snapshot_prebuilt: '1'
          - lane: snapshot-acp-8
            command: pnpm run check:ci:snapshot
            gate_concurrency: '1'
            snapshot_lane: acp-8
            snapshot_max_concurrency: '5'
            snapshot_prebuilt: '1'
          - lane: artifacts-metadata
            command: pnpm run check:ci:artifacts
            gate_concurrency: '3'
            publint_concurrency: '8'
            artifact_shard: metadata
          - lane: artifacts-smoke
            command: pnpm run check:ci:artifacts
            gate_concurrency: '1'
            artifact_shard: smoke
    steps:
      - uses: actions/checkout@v6

      - uses: actions/setup-node@v6
        with:
          node-version: ${{ env.PRIMARY_NODE_VERSION }}

      - name: Enable corepack and resolve pnpm store path
        id: pnpm-store
        run: |
          corepack enable
          echo "path=$(pnpm store path --silent)" >> "$GITHUB_OUTPUT"

      - uses: actions/cache@v4
        with:
          path: ${{ steps.pnpm-store.outputs.path }}
          key: ${{ runner.os }}-node-${{ env.PRIMARY_NODE_VERSION }}-pnpm-${{ hashFiles('pnpm-lock.yaml') }}
          restore-keys: |
            ${{ runner.os }}-node-${{ env.PRIMARY_NODE_VERSION }}-pnpm-

      - name: Install (immutable)
        if: ${{ ! startsWith(matrix.lane, 'snapshot-') }}
        run: pnpm install --frozen-lockfile

      # The snapshot lanes REPLAY the sandbox example's recorded scenarios,
      # re-executing their bash calls under a real runner. ubuntu-latest has
      # no bubblewrap preinstalled and no built Landlock launcher, so without
      # this the confined executions fail closed (SANDBOX_UNAVAILABLE). The
      # install retries after refreshing stale indexes and applies the Ubuntu
      # 24.04 AppArmor userns knob. Bubblewrap preparation is independent of
      # dependency installation and the build, so it runs beside both.
      - name: Install and prepare built snapshot runtime and bubblewrap
        if: startsWith(matrix.lane, 'snapshot-')
        run: |
          pnpm install --frozen-lockfile &
          install_pid=$!
          (
            if ! sudo apt-get install -yq --no-install-recommends bubblewrap; then
              echo "initial bubblewrap install failed; refreshing APT indexes and retrying"
              sudo apt-get update -q
              sudo apt-get install -yq --no-install-recommends bubblewrap
            fi
            sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0 \
              || echo "apparmor userns knob absent — the functional probe decides"
          ) &
          sandbox_pid=$!
          install_status=0
          wait "$install_pid" || install_status=$?
          build_status=0
          if (( install_status == 0 )); then
            pnpm run build || build_status=$?
          fi
          sandbox_status=0
          wait "$sandbox_pid" || sandbox_status=$?
          if (( install_status != 0 )); then exit "$install_status"; fi
          if (( build_status != 0 )); then exit "$build_status"; fi
          exit "$sandbox_status"

      - uses: actions/cache@v4
        if: startsWith(matrix.lane, 'lint-')
        with:
          path: .cache/eslint
          key: ${{ runner.os }}-node-${{ env.PRIMARY_NODE_VERSION }}-eslint-${{ matrix.lint_shard }}-${{ hashFiles('pnpm-lock.yaml', 'eslint.config.mjs', 'tsconfig.json', 'packages/*/*/tsconfig.json', 'examples/*/tsconfig.json') }}
          restore-keys: |
            ${{ runner.os }}-node-${{ env.PRIMARY_NODE_VERSION }}-eslint-${{ matrix.lint_shard }}-

      - name: Run gates
        run: ${{ matrix.command }}

  # One large runner pays hosted setup once, then the repository scheduler
  # overlaps the unsharded primary inventory except the production site build.
  node-24:
    if: github.event_name != 'workflow_dispatch' || inputs.suite == 'optimized-larger-runners'
    runs-on: dsh-ubuntu-24-04-96core
    name: node 24 / core
    env:
      # Thirty-two Vitest forks intermittently crash Node's CJS lexer on this image.
      DSH_COVERAGE_MAX_WORKERS: '16'
      DSH_ESLINT_CACHE: '1'
      DSH_ESLINT_CONCURRENCY: '32'
      DSH_GATE_CONCURRENCY: '32'
      DSH_PUBLINT_CONCURRENCY: '32'
      DSH_SNAPSHOT_MAX_CONCURRENCY: '32'
    steps:
      - uses: actions/checkout@v6

      - uses: actions/setup-node@v6
        with:
          node-version: ${{ env.PRIMARY_NODE_VERSION }}

      - name: Enable corepack and resolve pnpm store path
        id: pnpm-store
        run: |
          corepack enable
          echo "path=$(pnpm store path --silent)" >> "$GITHUB_OUTPUT"

      - uses: actions/cache@v4
        with:
          path: ${{ steps.pnpm-store.outputs.path }}
          key: ${{ runner.os }}-node-${{ env.PRIMARY_NODE_VERSION }}-pnpm-${{ hashFiles('pnpm-lock.yaml') }}
          restore-keys: |
            ${{ runner.os }}-node-${{ env.PRIMARY_NODE_VERSION }}-pnpm-

      - uses: actions/cache@v4
        with:
          path: .cache/eslint
          key: ${{ runner.os }}-node-${{ env.PRIMARY_NODE_VERSION }}-eslint-full-${{ hashFiles('pnpm-lock.yaml', 'eslint.config.mjs', 'tsconfig.json', 'packages/*/*/tsconfig.json', 'examples/*/tsconfig.json') }}
          restore-keys: |
            ${{ runner.os }}-node-${{ env.PRIMARY_NODE_VERSION }}-eslint-full-

      - name: Install and prepare bubblewrap
        run: |
          pnpm install --frozen-lockfile &
          install_pid=$!
          (
            if ! sudo apt-get install -yq --no-install-recommends bubblewrap; then
              echo "initial bubblewrap install failed; refreshing APT indexes and retrying"
              sudo apt-get update -q
              sudo apt-get install -yq --no-install-recommends bubblewrap
            fi
            sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0 \
              || echo "apparmor userns knob absent — the functional probe decides"
          ) &
          sandbox_pid=$!
          install_status=0
          wait "$install_pid" || install_status=$?
          sandbox_status=0
          wait "$sandbox_pid" || sandbox_status=$?
          if (( install_status != 0 )); then exit "$install_status"; fi
          exit "$sandbox_status"

      - name: Run unsharded primary Node core CI concurrently
        run: pnpm run check:ci:large-runner

  # Keep only the longest independent Linux gate on a second coarse-grained
  # runner so cold install variance does not push the primary box over a minute.
  node-24-site:
    if: github.event_name != 'workflow_dispatch' || inputs.suite == 'optimized-larger-runners'
    runs-on: dsh-ubuntu-24-04-16core
    name: node 24 / production site
    steps:
      - uses: actions/checkout@v6

      - uses: actions/setup-node@v6
        with:
          node-version: ${{ env.PRIMARY_NODE_VERSION }}

      - name: Enable corepack and resolve pnpm store path
        id: pnpm-store
        run: |
          corepack enable
          echo "path=$(pnpm store path --silent)" >> "$GITHUB_OUTPUT"

      - uses: actions/cache@v4
        with:
          path: ${{ steps.pnpm-store.outputs.path }}
          key: ${{ runner.os }}-node-${{ env.PRIMARY_NODE_VERSION }}-pnpm-${{ hashFiles('pnpm-lock.yaml') }}
          restore-keys: |
            ${{ runner.os }}-node-${{ env.PRIMARY_NODE_VERSION }}-pnpm-

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

      - name: Build documentation site (production SPA)
        run: pnpm run docs:build

  node-compat:
    if: github.event_name != 'workflow_dispatch' || inputs.suite == 'optimized-larger-runners'
    runs-on: ubuntu-latest
    name: node ${{ matrix.node }}
    env:
      DSH_GATE_CONCURRENCY: '2'
      DSH_NODE_COMPAT_SKIP_TYPECHECK: ${{ matrix.skip_typecheck }}
    strategy:
      fail-fast: false
      matrix:
        include:
          - node: '22.19'
            skip_typecheck: '1'
          - node: 24
            skip_typecheck: '1'
          - node: 26
            skip_typecheck: '1'
    steps:
      - uses: actions/checkout@v6

      - uses: actions/setup-node@v6
        with:
          node-version: ${{ matrix.node }}

      - name: Enable corepack and resolve pnpm store path
        id: pnpm-store
        run: |
          corepack enable
          echo "path=$(pnpm store path --silent)" >> "$GITHUB_OUTPUT"

      - uses: actions/cache@v4
        with:
          path: ${{ steps.pnpm-store.outputs.path }}
          key: ${{ runner.os }}-node-${{ matrix.node }}-pnpm-${{ hashFiles('pnpm-lock.yaml') }}
          restore-keys: |
            ${{ runner.os }}-node-${{ matrix.node }}-pnpm-

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

      - name: Run compatibility gates
        run: pnpm run check:node-compat

  python-sdk:
    if: github.event_name != 'workflow_dispatch' || inputs.suite == 'optimized-larger-runners'
    runs-on: ubuntu-latest
    name: python 3.10 / keyless SDK
    steps:
      - uses: actions/checkout@v6

      - uses: actions/setup-python@v6
        with:
          python-version: '3.10'
          cache: pip

      - name: Install uv
        run: python -m pip install uv==0.11.23

      - name: Run complete keyless Python suite
        run: uv run --python 3.10 --group test --project python/sdk pytest

  # Manual sharded Windows reference matching the former production topology.
  # Blocking build and production-site lanes keep the already-green
  # native outputs protected without putting both critical paths in one job.
  # The broader observational gate matrix below exposes the remaining
  # portability work without blocking mainline merges.
  windows-build-sharded:
    if: github.event_name == 'workflow_dispatch' && inputs.suite == 'sharded-reference'
    runs-on: dsh-windows-2025-4core
    name: windows / build
    steps:
      - uses: actions/checkout@v6

      - uses: actions/setup-node@v6
        with:
          node-version: ${{ env.PRIMARY_NODE_VERSION }}

      - name: Install (immutable)
        run: |
          corepack enable
          pnpm install --frozen-lockfile

      - name: Build (tsc -b + tsdown)
        run: pnpm run build

  windows-site-sharded:
    if: github.event_name == 'workflow_dispatch' && inputs.suite == 'sharded-reference'
    runs-on: dsh-windows-2025-4core
    name: windows / production site
    steps:
      - uses: actions/checkout@v6

      - uses: actions/setup-node@v6
        with:
          node-version: ${{ env.PRIMARY_NODE_VERSION }}

      - name: Install (immutable)
        run: |
          corepack enable
          pnpm install --frozen-lockfile

      - name: Build documentation site (production SPA)
        run: pnpm run docs:build

  # Observational, non-blocking Windows static, lint, and artifact lanes. Coverage
  # and snapshot stay Linux-only until their platform-specific runtime failures
  # have dedicated support. Run the gates from native PowerShell: an MSYS parent
  # would change the environment being measured. This job intentionally stays
  # out of all-checks-passed.needs.
  windows-gates-sharded:
    if: github.event_name == 'workflow_dispatch' && inputs.suite == 'sharded-reference'
    continue-on-error: true
    runs-on: dsh-windows-2025-4core
    name: windows node 24 / ${{ matrix.lane }}
    env:
      DSH_GATE_CONCURRENCY: ${{ matrix.gate_concurrency }}
      DSH_PUBLINT_CONCURRENCY: ${{ matrix.publint_concurrency }}
      DSH_ARTIFACT_SHARD: ${{ matrix.artifact_shard }}
      DSH_LINT_SHARD: ${{ matrix.lint_shard }}
      DSH_STATIC_SHARD: ${{ matrix.static_shard }}
      DSH_ESLINT_CACHE: ${{ matrix.eslint_cache }}
    strategy:
      fail-fast: false
      matrix:
        include:
          - lane: static-general
            command: pnpm run check:ci:static
            gate_concurrency: '4'
            static_shard: 'foundation,catalogs,prose'
          - lane: static-contracts
            command: pnpm run check:ci:static
            gate_concurrency: '4'
            static_shard: 'doc-types,api-contracts'
          - lane: lint-package-sources
            command: pnpm run check:ci:lint
            gate_concurrency: '1'
            eslint_cache: '1'
            lint_shard: package-sources
          - lane: lint-package-tests
            command: pnpm run check:ci:lint
            gate_concurrency: '1'
            eslint_cache: '1'
            lint_shard: package-tests
          - lane: lint-repository
            command: pnpm run check:ci:lint
            gate_concurrency: '1'
            eslint_cache: '1'
            lint_shard: repository
          - lane: artifacts-metadata
            command: pnpm run check:ci:artifacts
            gate_concurrency: '3'
            publint_concurrency: '8'
            artifact_shard: metadata
          - lane: artifacts-smoke
            command: pnpm run check:ci:artifacts
            gate_concurrency: '1'
            artifact_shard: smoke
    steps:
      - uses: actions/checkout@v6

      - name: Enable Developer Mode (symlink support)
        shell: pwsh
        run: >-
          reg add "HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\AppModelUnlock"
          /t REG_DWORD /f /v "AllowDevelopmentWithoutDevLicense" /d "1"

      - uses: actions/setup-node@v6
        with:
          node-version: ${{ env.PRIMARY_NODE_VERSION }}

      - name: Enable corepack and resolve pnpm store path
        id: pnpm-store
        shell: pwsh
        run: |
          corepack enable
          "path=$(pnpm store path --silent)" >> $env:GITHUB_OUTPUT

      - uses: actions/cache@v4
        with:
          path: ${{ steps.pnpm-store.outputs.path }}
          key: ${{ runner.os }}-node-${{ env.PRIMARY_NODE_VERSION }}-pnpm-${{ hashFiles('pnpm-lock.yaml') }}
          restore-keys: |
            ${{ runner.os }}-node-${{ env.PRIMARY_NODE_VERSION }}-pnpm-

      - name: Install (immutable)
        shell: pwsh
        run: pnpm install --frozen-lockfile

      - uses: actions/cache@v4
        if: startsWith(matrix.lane, 'lint-')
        with:
          path: .cache/eslint
          key: ${{ runner.os }}-node-${{ env.PRIMARY_NODE_VERSION }}-eslint-${{ matrix.lint_shard }}-${{ hashFiles('pnpm-lock.yaml', 'eslint.config.mjs', 'tsconfig.json', 'packages/*/*/tsconfig.json', 'examples/*/tsconfig.json') }}
          restore-keys: |
            ${{ runner.os }}-node-${{ env.PRIMARY_NODE_VERSION }}-eslint-${{ matrix.lint_shard }}-

      - name: Run gates
        shell: pwsh
        run: ${{ matrix.command }}

  # One Windows box shares setup across the required build/site checks and the
  # complete observational portability inventory. run-gates reports failures
  # from observational gates without allowing them to fail the required job.
  windows:
    if: github.event_name != 'workflow_dispatch' || inputs.suite == 'optimized-larger-runners'
    runs-on: dsh-windows-2025-32core
    name: windows node 24 / complete
    env:
      # Keep ESLint itself single-threaded: 16 ESLint workers took 174 seconds on
      # this image. The outer scheduler still overlaps lint with the other gates.
      DSH_ESLINT_CACHE: '1'
      DSH_GATE_CONCURRENCY: '32'
      DSH_PUBLINT_CONCURRENCY: '32'
    steps:
      - uses: actions/checkout@v6

      - name: Enable Developer Mode (symlink support)
        shell: pwsh
        run: >-
          reg add "HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\AppModelUnlock"
          /t REG_DWORD /f /v "AllowDevelopmentWithoutDevLicense" /d "1"

      - uses: actions/setup-node@v6
        with:
          node-version: ${{ env.PRIMARY_NODE_VERSION }}

      - name: Enable corepack and resolve pnpm store path
        id: pnpm-store
        shell: pwsh
        run: |
          corepack enable
          "path=$(pnpm store path --silent)" >> $env:GITHUB_OUTPUT

      - uses: actions/cache@v4
        with:
          path: ${{ steps.pnpm-store.outputs.path }}
          key: ${{ runner.os }}-node-${{ env.PRIMARY_NODE_VERSION }}-pnpm-${{ hashFiles('pnpm-lock.yaml') }}
          restore-keys: |
            ${{ runner.os }}-node-${{ env.PRIMARY_NODE_VERSION }}-pnpm-

      - uses: actions/cache@v4
        with:
          path: .cache/eslint
          key: ${{ runner.os }}-node-${{ env.PRIMARY_NODE_VERSION }}-eslint-full-${{ hashFiles('pnpm-lock.yaml', 'eslint.config.mjs', 'tsconfig.json', 'packages/*/*/tsconfig.json', 'examples/*/tsconfig.json') }}
          restore-keys: |
            ${{ runner.os }}-node-${{ env.PRIMARY_NODE_VERSION }}-eslint-full-

      - name: Install (immutable)
        shell: pwsh
        run: pnpm install --frozen-lockfile

      - name: Run blocking and observational Windows gates concurrently
        shell: pwsh
        run: pnpm run check:ci:windows-complete

  # Manual reference runs deliberately avoid the optimized jobs above.
  # Each host executes the complete, unsharded primary Node aggregate with one
  # gate worker, giving reviewers a simple cross-platform oracle for completeness
  # and timing.
  serial-linux:
    if: github.event_name == 'workflow_dispatch' && inputs.suite == 'serial-reference'
    name: serial / linux
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - uses: actions/setup-node@v6
        with:
          node-version: ${{ env.PRIMARY_NODE_VERSION }}

      - name: Enable corepack (pnpm)
        run: corepack enable

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

      - name: Install bubblewrap (unrestrict userns)
        run: |
          sudo apt-get update -q
          sudo apt-get install -yq --no-install-recommends bubblewrap
          sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0 \
            || echo "apparmor userns knob absent — the functional probe decides"

      - name: Run complete unsharded primary Node CI serially
        env:
          DSH_COVERAGE_MAX_WORKERS: '1'
          DSH_E2E_MAX_WORKERS: '1'
          DSH_GATE_CONCURRENCY: '1'
          DSH_PUBLINT_CONCURRENCY: '1'
          DSH_SNAPSHOT_MAX_CONCURRENCY: '1'
        run: pnpm run check:ci

  serial-macos:
    if: github.event_name == 'workflow_dispatch' && inputs.suite == 'serial-reference'
    name: serial / macos
    runs-on: macos-latest
    steps:
      - uses: actions/checkout@v6

      - uses: actions/setup-node@v6
        with:
          node-version: ${{ env.PRIMARY_NODE_VERSION }}

      - name: Enable corepack (pnpm)
        run: corepack enable

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

      - name: Run complete unsharded primary Node CI serially
        env:
          DSH_COVERAGE_MAX_WORKERS: '1'
          DSH_E2E_MAX_WORKERS: '1'
          DSH_GATE_CONCURRENCY: '1'
          DSH_PUBLINT_CONCURRENCY: '1'
          DSH_SNAPSHOT_MAX_CONCURRENCY: '1'
        run: pnpm run check:ci

  serial-windows:
    if: github.event_name == 'workflow_dispatch' && inputs.suite == 'serial-reference'
    name: serial / windows
    runs-on: windows-2025
    steps:
      - uses: actions/checkout@v6

      - name: Enable Developer Mode (symlink support)
        shell: pwsh
        run: >-
          reg add "HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\AppModelUnlock"
          /t REG_DWORD /f /v "AllowDevelopmentWithoutDevLicense" /d "1"

      - uses: actions/setup-node@v6
        with:
          node-version: ${{ env.PRIMARY_NODE_VERSION }}

      - name: Enable corepack (pnpm)
        shell: pwsh
        run: corepack enable

      - name: Install (immutable)
        shell: pwsh
        run: pnpm install --frozen-lockfile

      - name: Run complete unsharded primary Node CI serially
        shell: pwsh
        env:
          DSH_COVERAGE_MAX_WORKERS: '1'
          DSH_E2E_MAX_WORKERS: '1'
          DSH_GATE_CONCURRENCY: '1'
          DSH_PUBLINT_CONCURRENCY: '1'
          DSH_SNAPSHOT_MAX_CONCURRENCY: '1'
        run: pnpm run check:ci

  # Manual, bounded comparison of the actual critical Linux and Windows lanes.
  # The named pools are restricted at the organization level to this repository.
  larger-runner-benchmark:
    if: github.event_name == 'workflow_dispatch' && inputs.suite == 'larger-runner-benchmark'
    name: larger runner / ${{ matrix.platform }} / ${{ matrix.cores }} cores / ${{ matrix.workload }}
    runs-on: ${{ matrix.runner }}
    timeout-minutes: 15
    strategy:
      fail-fast: false
      max-parallel: 12
      matrix:
        include:
          - platform: linux
            cores: '4'
            runner: dsh-ubuntu-24-04-4core
            workload: typecheck
          - platform: linux
            cores: '8'
            runner: dsh-ubuntu-24-04-8core
            workload: typecheck
          - platform: linux
            cores: '16'
            runner: dsh-ubuntu-24-04-16core
            workload: typecheck
          - platform: linux
            cores: '32'
            runner: dsh-ubuntu-24-04-32core
            workload: typecheck
          - platform: linux
            cores: '64'
            runner: dsh-ubuntu-24-04-64core
            workload: typecheck
          - platform: linux
            cores: '96'
            runner: dsh-ubuntu-24-04-96core
            workload: typecheck
          - platform: windows
            cores: '4'
            runner: dsh-windows-2025-4core
            workload: production-site
          - platform: windows
            cores: '8'
            runner: dsh-windows-2025-8core
            workload: production-site
          - platform: windows
            cores: '16'
            runner: dsh-windows-2025-16core
            workload: production-site
          - platform: windows
            cores: '32'
            runner: dsh-windows-2025-32core
            workload: production-site
          - platform: windows
            cores: '64'
            runner: dsh-windows-2025-64core
            workload: production-site
          - platform: windows
            cores: '96'
            runner: dsh-windows-2025-96core
            workload: production-site
    steps:
      - uses: actions/checkout@v6

      - uses: actions/setup-node@v6
        with:
          node-version: ${{ env.PRIMARY_NODE_VERSION }}

      - name: Report runner capacity
        run: >-
          node -e "const os = require('node:os');
          console.log(JSON.stringify({ arch: process.arch, cpus: os.cpus().length,
          memoryGiB: Math.round(os.totalmem() / 2 ** 30) }))"

      - name: Enable corepack (pnpm)
        run: corepack enable

      - name: Resolve pnpm store path
        if: matrix.platform == 'linux'
        id: pnpm-store
        run: echo "path=$(pnpm store path --silent)" >> "$GITHUB_OUTPUT"

      - uses: actions/cache@v4
        if: matrix.platform == 'linux'
        with:
          path: ${{ steps.pnpm-store.outputs.path }}
          key: ${{ runner.os }}-node-${{ env.PRIMARY_NODE_VERSION }}-pnpm-${{ hashFiles('pnpm-lock.yaml') }}
          restore-keys: |
            ${{ runner.os }}-node-${{ env.PRIMARY_NODE_VERSION }}-pnpm-

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

      - name: Run critical Linux typecheck lane
        if: matrix.platform == 'linux'
        run: pnpm run typecheck

      - name: Run critical Windows production-site lane
        if: matrix.platform == 'windows'
        run: pnpm run docs:build

  # Manual comparison of the intended low-fanout topology. Linux runs the
  # complete unsharded primary aggregate with bounded in-runner parallelism;
  # Windows runs both blocking build surfaces concurrently through run-gates.
  consolidated-runner-benchmark:
    if: github.event_name == 'workflow_dispatch' && inputs.suite == 'consolidated-runner-benchmark'
    name: consolidated / ${{ matrix.platform }} / ${{ matrix.cores }} cores
    runs-on: ${{ matrix.runner }}
    timeout-minutes: 15
    strategy:
      fail-fast: false
      max-parallel: 12
      matrix:
        include:
          - platform: linux
            cores: '4'
            runner: dsh-ubuntu-24-04-4core
            workers: '4'
          - platform: linux
            cores: '8'
            runner: dsh-ubuntu-24-04-8core
            workers: '8'
          - platform: linux
            cores: '16'
            runner: dsh-ubuntu-24-04-16core
            workers: '16'
          - platform: linux
            cores: '32'
            runner: dsh-ubuntu-24-04-32core
            workers: '32'
          - platform: linux
            cores: '64'
            runner: dsh-ubuntu-24-04-64core
            workers: '32'
          - platform: linux
            cores: '96'
            runner: dsh-ubuntu-24-04-96core
            workers: '32'
          - platform: windows
            cores: '4'
            runner: dsh-windows-2025-4core
            workers: '2'
          - platform: windows
            cores: '8'
            runner: dsh-windows-2025-8core
            workers: '2'
          - platform: windows
            cores: '16'
            runner: dsh-windows-2025-16core
            workers: '2'
          - platform: windows
            cores: '32'
            runner: dsh-windows-2025-32core
            workers: '2'
          - platform: windows
            cores: '64'
            runner: dsh-windows-2025-64core
            workers: '2'
          - platform: windows
            cores: '96'
            runner: dsh-windows-2025-96core
            workers: '2'
    steps:
      - uses: actions/checkout@v6

      - uses: actions/setup-node@v6
        with:
          node-version: ${{ env.PRIMARY_NODE_VERSION }}

      - name: Report runner capacity
        run: >-
          node -e "const os = require('node:os');
          console.log(JSON.stringify({ arch: process.arch, cpus: os.cpus().length,
          memoryGiB: Math.round(os.totalmem() / 2 ** 30) }))"

      - name: Enable corepack (pnpm)
        run: corepack enable

      - name: Resolve pnpm store path (Linux)
        if: matrix.platform == 'linux'
        id: pnpm-store-linux
        run: echo "path=$(pnpm store path --silent)" >> "$GITHUB_OUTPUT"

      - name: Resolve pnpm store path (Windows)
        if: matrix.platform == 'windows'
        id: pnpm-store-windows
        shell: pwsh
        run: '"path=$(pnpm store path --silent)" >> $env:GITHUB_OUTPUT'

      - uses: actions/cache@v4
        with:
          path: ${{ steps.pnpm-store-linux.outputs.path || steps.pnpm-store-windows.outputs.path }}
          key: ${{ runner.os }}-node-${{ env.PRIMARY_NODE_VERSION }}-pnpm-${{ hashFiles('pnpm-lock.yaml') }}
          restore-keys: |
            ${{ runner.os }}-node-${{ env.PRIMARY_NODE_VERSION }}-pnpm-

      - uses: actions/cache@v4
        if: matrix.platform == 'linux'
        with:
          path: .cache/eslint
          key: ${{ runner.os }}-node-${{ env.PRIMARY_NODE_VERSION }}-eslint-full-${{ hashFiles('pnpm-lock.yaml', 'eslint.config.mjs', 'tsconfig.json', 'packages/*/*/tsconfig.json', 'examples/*/tsconfig.json') }}
          restore-keys: |
            ${{ runner.os }}-node-${{ env.PRIMARY_NODE_VERSION }}-eslint-full-

      - name: Install and prepare Linux
        if: matrix.platform == 'linux'
        run: |
          pnpm install --frozen-lockfile &
          install_pid=$!
          (
            if ! sudo apt-get install -yq --no-install-recommends bubblewrap; then
              echo "initial bubblewrap install failed; refreshing APT indexes and retrying"
              sudo apt-get update -q
              sudo apt-get install -yq --no-install-recommends bubblewrap
            fi
            sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0 \
              || echo "apparmor userns knob absent — the functional probe decides"
          ) &
          sandbox_pid=$!
          install_status=0
          wait "$install_pid" || install_status=$?
          sandbox_status=0
          wait "$sandbox_pid" || sandbox_status=$?
          if (( install_status != 0 )); then exit "$install_status"; fi
          exit "$sandbox_status"

      - name: Install (immutable)
        if: matrix.platform == 'windows'
        shell: pwsh
        run: pnpm install --frozen-lockfile

      - name: Run complete unsharded primary Node CI concurrently
        if: matrix.platform == 'linux'
        env:
          DSH_COVERAGE_MAX_WORKERS: ${{ matrix.workers }}
          DSH_ESLINT_CACHE: '1'
          DSH_ESLINT_CONCURRENCY: ${{ matrix.workers }}
          DSH_GATE_CONCURRENCY: ${{ matrix.workers }}
          DSH_PUBLINT_CONCURRENCY: ${{ matrix.workers }}
          DSH_SNAPSHOT_MAX_CONCURRENCY: ${{ matrix.workers }}
        run: pnpm run check:ci

      - name: Run blocking Windows builds concurrently
        if: matrix.platform == 'windows'
        shell: pwsh
        env:
          DSH_GATE_CONCURRENCY: ${{ matrix.workers }}
        run: pnpm run check:ci:windows-blocking

  # Single stable required check for branch protection: require "all checks
  # passed" instead of enumerating matrix legs whose names change as lanes and
  # node versions evolve. Every blocking job in THIS workflow must be listed in
  # `needs`; observational Windows gates share the required Windows job but are
  # marked non-blocking inside run-gates. (`needs` cannot reach across workflow
  # files; e2e.yml stays its own check.)
  # `if: always()` is load-bearing: without it a failed dependency
  # would SKIP this job, and GitHub counts a skipped required check as passing
  # — so this job always runs and fails on any non-success result, including
  # 'cancelled' and 'skipped'.
  all-checks-passed:
    name: all checks passed
    runs-on: ubuntu-latest
    needs: [node-24, node-24-site, node-compat, python-sdk, windows]
    if: always() && (github.event_name != 'workflow_dispatch' || inputs.suite == 'optimized-larger-runners')
    steps:
      - name: Fail if any needed job did not succeed
        if: contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled') || contains(needs.*.result, 'skipped')
        run: |
          echo "::error::Needed job results: ${{ join(needs.*.result, ', ') }}"
          exit 1
      - name: All checks passed
        run: echo "All needed jobs succeeded (${{ join(needs.*.result, ', ') }})"