Consolidate repository tools and flatten Runtime sources

.github/CODEOWNERS

@@ -12,7 +12,7 @@
 # Current source compiler and Runtime ownership.
 /compiler/ @zhoubot @xiekunpeng
 /schemas/ @zhoubot @xiekunpeng
-/simulator/gfsim/ @zhoubot @xiekunpeng
+/runtime/ @zhoubot @xiekunpeng
 /tests/compiler/ @zhoubot @xiekunpeng
 /tests/runtime/ @zhoubot @xiekunpeng
 /tests/integration/ @zhoubot @xiekunpeng

.github/scripts/validate_repo_management.py

@@ -72,7 +72,7 @@ def ancestors(name: str, active: frozenset[str] = frozenset()) -> set[str]:
             errors.append(f"release publication job {name} bypasses accept-candidate")
 
     rebuild_markers = (
-        "flows/scripts/pyc build",
+        "tools/pyc build",
         "cmake --build",
         "python3 -m build",
         "create_wheel.py",
@@ -213,7 +213,7 @@ def main() -> int:
         require(command in ci, f"CI is missing required gate: {command}", errors)
     for forbidden in (
         "llvm.sh",
-        "flows/scripts/pyc build",
+        "tools/pyc build",
         "setup-verilator",
         "run_examples.sh",
         "run_api_tests.sh",
@@ -249,7 +249,7 @@ def main() -> int:
         "run_examples.sh",
         "run_api_tests.sh",
         "pytest tests/unit -m unit",
-        "flows/tools/check_api_hygiene.py",
+        "tools/check_api_hygiene.py",
         "mkdocs build --strict",
     ):
         require(

.github/workflows/ci-macos.yml

@@ -40,7 +40,7 @@ jobs:
       - name: Build staged toolchain
         run: |
           LLVM_CONFIG="$(brew --prefix "llvm@${LLVM_VERSION}")/bin/llvm-config" \
-          bash flows/scripts/pyc build \
+          bash tools/pyc build \
             --build-dir "$PWD/.pycircuit_out/toolchain/build" \
             --install-prefix "$PWD/.pycircuit_out/toolchain/install"
 
@@ -95,7 +95,7 @@ jobs:
           export PYC_TOOLCHAIN_ROOT="$PWD/.pycircuit_out/toolchain/install"
           export PATH="$PYC_TOOLCHAIN_ROOT/bin:$PATH"
           unset PYCC
-          bash flows/scripts/run_examples.sh --tier gate
+          bash tools/run_examples.sh --tier gate
 
       - name: Smoke test installed wheel
         shell: bash
@@ -107,10 +107,10 @@ jobs:
           export PYC_TOOLCHAIN_ROOT="$(python -c 'import pycircuit, pathlib; print((pathlib.Path(pycircuit.__file__).resolve().parent / "_toolchain").as_posix())')"
           export PYC_USE_INSTALLED_PYTHON_PACKAGE=1
           unset PYCC
-          bash flows/scripts/run_examples.sh --tier gate
+          bash tools/run_examples.sh --tier gate
 
       - name: Check installed toolchain retirement inventory
-        run: python flows/tools/check_frontend_retirement.py --install-root "$PWD/.pycircuit_out/toolchain/install"
+        run: python tools/check_frontend_retirement.py --install-root "$PWD/.pycircuit_out/toolchain/install"
 
       - name: Upload wheel
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7

.github/workflows/ci.yml

@@ -66,10 +66,10 @@ jobs:
             packaging/wheel/platform_tags.py \
             python/pycircuit/packaged_toolchain.py \
             python/pycircuit/cli.py \
-            flows/tools/summarize_gate_run.py
+            tools/summarize_gate_run.py
 
       - name: Run API hygiene gate
-        run: python flows/tools/check_api_hygiene.py python/pycircuit examples docs README.md
+        run: python tools/check_api_hygiene.py python/pycircuit examples docs README.md
 
   capture-publication-gates:
     name: "G0: Capture and Publication Unit Gates"

.github/workflows/closure-probe.yml

@@ -59,7 +59,7 @@ jobs:
       - name: Build integrated toolchain
         run: |
           export PYC_PYTHON_EXECUTABLE="$(command -v python3)"
-          PYC_BUILD_TESTING=ON bash flows/scripts/pyc build --build-dir "$PWD/.pycircuit_out/toolchain/build" --install-prefix "$PWD/.pycircuit_out/toolchain/install"
+          PYC_BUILD_TESTING=ON bash tools/pyc build --build-dir "$PWD/.pycircuit_out/toolchain/build" --install-prefix "$PWD/.pycircuit_out/toolchain/install"
 
       - name: Repository contract closure
         id: contracts
@@ -68,7 +68,7 @@ jobs:
           SKIP=pyc-api-hygiene pre-commit run --all-files
           python3 .github/scripts/validate_repo_management.py
           pytest tests/unit -m unit
-          python3 flows/tools/check_api_hygiene.py python/pycircuit examples docs README.md
+          python3 tools/check_api_hygiene.py python/pycircuit examples docs README.md
           mkdocs build --strict
 
       - name: pyCircuit closure (examples)
@@ -77,15 +77,15 @@ jobs:
         run: |
           export PYC_TOOLCHAIN_ROOT="$PWD/.pycircuit_out/toolchain/install"
           export PATH="$PYC_TOOLCHAIN_ROOT/bin:$PATH"
-          bash flows/scripts/run_examples.sh --tier nightly
+          bash tools/run_examples.sh --tier nightly
 
       - name: pyCircuit closure (API nightly)
         id: api
         continue-on-error: true
         run: |
           export PYC_TOOLCHAIN_ROOT="$PWD/.pycircuit_out/toolchain/install"
           export PATH="$PYC_TOOLCHAIN_ROOT/bin:$PATH"
-          bash flows/scripts/run_api_tests.sh --tier nightly
+          bash tools/run_api_tests.sh --tier nightly
 
       - name: Upload probe gate logs
         if: always()

.github/workflows/gates-nightly.yml

@@ -54,7 +54,7 @@ jobs:
       - name: Build staged toolchain
         run: |
           LLVM_CONFIG=/usr/lib/llvm-${LLVM_VERSION}/bin/llvm-config \
-          bash flows/scripts/pyc build \
+          bash tools/pyc build \
             --build-dir "$PWD/.pycircuit_out/toolchain/build" \
             --install-prefix "$PWD/.pycircuit_out/toolchain/install"
 
@@ -67,14 +67,14 @@ jobs:
           export PATH="$PYC_TOOLCHAIN_ROOT/bin:$PATH"
           export PYC_GATE_RUN_ID="${PYC_GATE_RUN_ID}"
           unset PYCC || true
-          bash flows/scripts/run_api_tests.sh --tier nightly
+          bash tools/run_api_tests.sh --tier nightly
 
       - name: Run examples (nightly)
         id: examples_nightly
         if: ${{ !cancelled() && steps.api_nightly.outcome != 'skipped' }}
         run: |
           export PYC_TOOLCHAIN_ROOT="$PWD/.pycircuit_out/toolchain/install"
-          bash flows/scripts/run_examples.sh --tier nightly
+          bash tools/run_examples.sh --tier nightly
 
       - name: Write gate summary
         if: always()
@@ -91,7 +91,7 @@ jobs:
           }
           api_status="$(map_outcome "${{ steps.api_nightly.outcome }}")"
           examples_status="$(map_outcome "${{ steps.examples_nightly.outcome }}")"
-          python3 flows/tools/summarize_gate_run.py \
+          python3 tools/summarize_gate_run.py \
             --run-id "${PYC_GATE_RUN_ID}" \
             --row "api-nightly:nightly:${api_status}" \
             --row "examples-nightly:nightly:${examples_status}" \

.github/workflows/platform-evidence.yml

@@ -295,7 +295,7 @@ jobs:
           export CFLAGS="-ffile-prefix-map=$GITHUB_WORKSPACE=. -fdebug-prefix-map=$GITHUB_WORKSPACE=."
           export CXXFLAGS="$CFLAGS"
           export PYC_PYTHON_EXECUTABLE="$(command -v python3)"
-          LLVM_CONFIG="${llvm_config}" bash flows/scripts/pyc build --build-dir "$PWD/.pycircuit_out/toolchain/build" --install-prefix "$PWD/.pycircuit_out/toolchain/install"
+          LLVM_CONFIG="${llvm_config}" bash tools/pyc build --build-dir "$PWD/.pycircuit_out/toolchain/build" --install-prefix "$PWD/.pycircuit_out/toolchain/install"
           mkdir -p candidate
           python3 packaging/wheel/create_wheel.py --install-dir "$PWD/.pycircuit_out/toolchain/install" --out-dir candidate --wheel-version "${{ inputs.version }}" --platform "${{ matrix.platform }}"
           wheel="$(find candidate -maxdepth 1 -name 'pycircuit_hisi-*.whl' -print -quit)"
@@ -355,7 +355,7 @@ jobs:
           $env:CFLAGS = $prefixMaps
           $env:CXXFLAGS = $prefixMaps
           $env:PYC_PYTHON_EXECUTABLE = (Get-Command python3).Source
-          pwsh -NoProfile -File flows/scripts/pyc.ps1 build --llvm-config "$llvmConfig" --build-dir "$PWD/.pycircuit_out/toolchain/build" --install-prefix "$PWD/.pycircuit_out/toolchain/install"
+          pwsh -NoProfile -File tools/pyc.ps1 build --llvm-config "$llvmConfig" --build-dir "$PWD/.pycircuit_out/toolchain/build" --install-prefix "$PWD/.pycircuit_out/toolchain/install"
           if ($LASTEXITCODE -ne 0) { throw "the platform SDK build failed with exit code $LASTEXITCODE" }
           New-Item -ItemType Directory -Force -Path candidate | Out-Null
           python3 packaging/wheel/create_wheel.py --install-dir "$PWD/.pycircuit_out/toolchain/install" --out-dir candidate --wheel-version "${{ inputs.version }}" --platform "${{ matrix.platform }}"

.github/workflows/release.yml

@@ -84,21 +84,21 @@ jobs:
       - name: Build integrated toolchain
         run: |
           export PYC_PYTHON_EXECUTABLE="$(command -v python3)"
-          PYC_BUILD_TESTING=ON bash flows/scripts/pyc build --build-dir "$PWD/.pycircuit_out/toolchain/build" --install-prefix "$PWD/.pycircuit_out/toolchain/install"
+          PYC_BUILD_TESTING=ON bash tools/pyc build --build-dir "$PWD/.pycircuit_out/toolchain/build" --install-prefix "$PWD/.pycircuit_out/toolchain/install"
       - name: Run repository contract closure
         run: |
           SKIP=pyc-api-hygiene pre-commit run --all-files
           python3 .github/scripts/validate_repo_management.py
           pytest tests/unit -m unit
-          python3 flows/tools/check_api_hygiene.py python/pycircuit examples docs README.md
+          python3 tools/check_api_hygiene.py python/pycircuit examples docs README.md
           mkdocs build --strict
       - name: Run full pyCircuit closure
         run: |
           export PYC_TOOLCHAIN_ROOT="$PWD/.pycircuit_out/toolchain/install"
           export PATH="$PYC_TOOLCHAIN_ROOT/bin:$PATH"
-          bash flows/scripts/run_api_tests.sh --tier nightly
-          bash flows/scripts/run_examples.sh --tier nightly
-          python3 flows/tools/check_frontend_retirement.py --install-root "$PYC_TOOLCHAIN_ROOT"
+          bash tools/run_api_tests.sh --tier nightly
+          bash tools/run_examples.sh --tier nightly
+          python3 tools/check_frontend_retirement.py --install-root "$PYC_TOOLCHAIN_ROOT"
       - name: Upload release gate logs
         if: always()
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
@@ -323,7 +323,7 @@ jobs:
           export CFLAGS="-ffile-prefix-map=$GITHUB_WORKSPACE=. -fdebug-prefix-map=$GITHUB_WORKSPACE=."
           export CXXFLAGS="$CFLAGS"
           export PYC_PYTHON_EXECUTABLE="$(command -v python3)"
-          LLVM_CONFIG="${llvm_config}" bash flows/scripts/pyc build --build-dir "$PWD/.pycircuit_out/toolchain/build" --install-prefix "$PWD/.pycircuit_out/toolchain/install"
+          LLVM_CONFIG="${llvm_config}" bash tools/pyc build --build-dir "$PWD/.pycircuit_out/toolchain/build" --install-prefix "$PWD/.pycircuit_out/toolchain/install"
           mkdir candidate
           python3 packaging/wheel/create_wheel.py --install-dir "$PWD/.pycircuit_out/toolchain/install" --out-dir candidate --wheel-version "${{ inputs.version }}" --platform "${{ matrix.platform }}"
           wheel="$(find candidate -maxdepth 1 -name 'pycircuit_hisi-*.whl' -print -quit)"
@@ -383,7 +383,7 @@ jobs:
           $env:CFLAGS = $prefixMaps
           $env:CXXFLAGS = $prefixMaps
           $env:PYC_PYTHON_EXECUTABLE = (Get-Command python3).Source
-          pwsh -NoProfile -File flows/scripts/pyc.ps1 build --llvm-config "$llvmConfig" --build-dir "$PWD/.pycircuit_out/toolchain/build" --install-prefix "$PWD/.pycircuit_out/toolchain/install"
+          pwsh -NoProfile -File tools/pyc.ps1 build --llvm-config "$llvmConfig" --build-dir "$PWD/.pycircuit_out/toolchain/build" --install-prefix "$PWD/.pycircuit_out/toolchain/install"
           if ($LASTEXITCODE -ne 0) { throw "the platform SDK build failed with exit code $LASTEXITCODE" }
           New-Item -ItemType Directory -Force -Path candidate | Out-Null
           python3 packaging/wheel/create_wheel.py --install-dir "$PWD/.pycircuit_out/toolchain/install" --out-dir candidate --wheel-version "${{ inputs.version }}" --platform "${{ matrix.platform }}"
@@ -677,7 +677,7 @@ jobs:
           arch: x64
           toolset: "14.4"
       - name: Redownload stable assets and verify exact bytes before execution
-        # flows/scripts and this step are POSIX shell; Git Bash ships with the
+        # tools and this step are POSIX shell; Git Bash ships with the
         # windows-2022 image, so the same script runs on all three lanes.
         shell: bash
         env:

.pre-commit-config.yaml

@@ -14,14 +14,14 @@ repos:
     rev: v0.11.8
     hooks:
       - id: ruff
-        exclude: ^(docs/gates/logs/|python/agentic-circuit/|compiler/|simulator/gfsim/|schemas/|examples/agentic-circuit/|tests/(python|mlir|cpp|integration|goldens)/agentic-circuit/|tools/agentic-circuit/|toolchains/|designs/blocks/BypassUnit/|designs/blocks/RegisterFile/)
+        exclude: ^(docs/gates/logs/|python/agentic-circuit/|compiler/|runtime/|schemas/|examples/agentic-circuit/|tests/(python|mlir|cpp|integration|goldens)/agentic-circuit/|tools/agentic-circuit/|toolchains/|designs/blocks/BypassUnit/|designs/blocks/RegisterFile/)
 
   - repo: https://github.com/psf/black
     rev: 24.10.0
     hooks:
       - id: black
         # pyproject.toml force-excludes source-span-sensitive compiler fixtures.
-        exclude: ^(docs/gates/logs/|python/agentic-circuit/|compiler/|simulator/gfsim/|schemas/|examples/agentic-circuit/|tests/(python|mlir|cpp|integration|goldens)/agentic-circuit/|tools/agentic-circuit/|toolchains/)
+        exclude: ^(docs/gates/logs/|python/agentic-circuit/|compiler/|runtime/|schemas/|examples/agentic-circuit/|tests/(python|mlir|cpp|integration|goldens)/agentic-circuit/|tools/agentic-circuit/|toolchains/)
 
   - repo: https://github.com/DavidAnson/markdownlint-cli2
     rev: v0.18.1
@@ -35,7 +35,7 @@ repos:
     hooks:
       - id: pyc-api-hygiene
         name: pyCircuit API hygiene gate
-        entry: python3 flows/tools/check_api_hygiene.py
+        entry: python3 tools/check_api_hygiene.py
         language: system
         files: ^(python/pycircuit/|examples/|docs/|README\.md$|CONTRIBUTING\.md$)
         exclude: ^(docs/gates/logs/|python/pycircuit/api_contract\.py$)

CMakeLists.txt

@@ -22,7 +22,7 @@ if(PYC_BUILD_TESTING)
   enable_testing()
 endif()
 if(PYC_BUILD_RUNTIME_LIB)
-  add_subdirectory(simulator/gfsim)
+  add_subdirectory(runtime)
 endif()
 if(PYC_BUILD_COMPILER_DEV)
   find_package(Python3 REQUIRED COMPONENTS Interpreter)

CONTRIBUTING.md

@@ -25,7 +25,7 @@ also use Icarus where supported.
 python3 -m venv .venv
 source .venv/bin/activate
 python -m pip install -e ".[dev,docs]"
-bash flows/scripts/pyc build
+bash tools/pyc build
 ```
 
 Build from this checkout and keep generated files in `.pycircuit_out/`. Do not
@@ -37,8 +37,8 @@ Start with the smallest test proving the change. PR CI runs bounded Python,
 repository, formatting and documentation checks. API and example tests use:
 
 ```bash
-bash flows/scripts/run_api_tests.sh --tier gate
-bash flows/scripts/run_examples.sh --tier gate
+bash tools/run_api_tests.sh --tier gate
+bash tools/run_examples.sh --tier gate
 ```
 
 Use `--tier nightly` for full registered coverage. Long oracle, mutation,

README.md

@@ -107,7 +107,7 @@ cd pyCircuit
 python3 -m venv .venv
 source .venv/bin/activate
 python -m pip install -e .
-PYC_BUILD_TESTING=OFF bash flows/scripts/pyc build
+PYC_BUILD_TESTING=OFF bash tools/pyc build
 
 export PYC_TOOLCHAIN_ROOT="$PWD/.pycircuit_out/toolchain/install"
 export PATH="$PYC_TOOLCHAIN_ROOT/bin:$PATH"
@@ -164,8 +164,8 @@ test dependencies, including GoogleTest and lit. With that testing build
 installed, run the bounded checks from the repository root:
 
 ```sh
-bash flows/scripts/run_api_tests.sh --tier gate
-bash flows/scripts/run_examples.sh --tier gate
+bash tools/run_api_tests.sh --tier gate
+bash tools/run_examples.sh --tier gate
 ```
 
 For a nondefault build, set `PYC_BUILD_DIR` and `PYC_TOOLCHAIN_ROOT` as described

benchmarks/README.md

@@ -8,12 +8,12 @@ Historical benchmark implementations remain in Git, outside the active route.
 
 The source-unit workload measures shared definitions at 1/16/64 instances and
 distinct leaves at 1/8/32 sources. Its generator and driver are owned here and
-in `flows/tools/`, respectively; see the [repository map](../docs/development/repository-layout.md). Generate
+in `tools/`, respectively; see the [repository map](../docs/development/repository-layout.md). Generate
 fixtures with `benchmarks/source-units/generate.py`, or run the full
 public-driver measurement from the checkout:
 
 ```sh
-python flows/tools/measure_source_build.py --prefix <installed-prefix> --output-dir .pycircuit_out/measurement-measure
+python tools/measure_source_build.py --prefix <installed-prefix> --output-dir .pycircuit_out/measurement-measure
 ```
 
 The output directory must be absent or empty. Prefix metadata must match the