clean blas and lapack examples

Author: saidctb

.github/workflows/blas-lapack.yml

@@ -63,15 +63,16 @@ jobs:
         env:
           PYTHONPATH: .
           HYPOTHESIS_PROFILE: ci
-        run: >-
-          python -m pytest -q -o "python_files=test_*.py ci_full_surface.py"
-          examples/blas examples/blas/ci_full_surface.py
+          PRIK_REAL_LIBRARY_NATIVE_CACHE_DIR: ${{ runner.temp }}/prik-real-library-native
+        run: |
+          source examples/blas/build_all.sh
+          python -m pytest -q examples/blas/tests examples/blas/ci/full_surface.py
       - name: Report reviewed LAPACK inventory
         env:
           PYTHONPATH: .
         run: |
           python - <<'PY'
-          from examples.lapack.f2py_contract import F2PY_INOUT_ARGUMENTS
+          from examples.lapack.f2py_build import F2PY_INOUT_ARGUMENTS
           from examples.lapack.routine_inventory import (
               EXPECTED_LAPACK_ROOT_PROCEDURES,
               EXPECTED_LAPACK_SOURCE_FILES,
@@ -93,6 +94,6 @@ jobs:
           PYTHONPATH: .
           HYPOTHESIS_PROFILE: ci
           PRIK_REAL_LIBRARY_NATIVE_CACHE_DIR: ${{ runner.temp }}/prik-real-library-native
-        run: >-
-          python -m pytest -q -o "python_files=test_*.py ci_full_surface.py"
-          examples/lapack examples/lapack/ci_full_surface.py
+        run: |
+          source examples/lapack/build_all.sh
+          python -m pytest -q examples/lapack/tests examples/lapack/ci/full_surface.py

.github/workflows/merge-validation.yml

@@ -618,15 +618,16 @@ jobs:
         env:
           PYTHONPATH: .
           HYPOTHESIS_PROFILE: ci
-        run: >-
-          python -m pytest -q -o "python_files=test_*.py ci_full_surface.py"
-          examples/blas examples/blas/ci_full_surface.py
+          PRIK_REAL_LIBRARY_NATIVE_CACHE_DIR: ${{ runner.temp }}/prik-real-library-native
+        run: |
+          source examples/blas/build_all.sh
+          python -m pytest -q examples/blas/tests examples/blas/ci/full_surface.py
       - name: Report reviewed LAPACK inventory
         env:
           PYTHONPATH: .
         run: |
           python - <<'PY'
-          from examples.lapack.f2py_contract import F2PY_INOUT_ARGUMENTS
+          from examples.lapack.f2py_build import F2PY_INOUT_ARGUMENTS
           from examples.lapack.routine_inventory import (
               EXPECTED_LAPACK_ROOT_PROCEDURES,
               EXPECTED_LAPACK_SOURCE_FILES,
@@ -648,9 +649,9 @@ jobs:
           PYTHONPATH: .
           HYPOTHESIS_PROFILE: ci
           PRIK_REAL_LIBRARY_NATIVE_CACHE_DIR: ${{ runner.temp }}/prik-real-library-native
-        run: >-
-          python -m pytest -q -o "python_files=test_*.py ci_full_surface.py"
-          examples/lapack examples/lapack/ci_full_surface.py
+        run: |
+          source examples/lapack/build_all.sh
+          python -m pytest -q examples/lapack/tests examples/lapack/ci/full_surface.py
 
   documentation-benchmark:
     name: Documentation performance benchmark · Ubuntu 24.04 ARM64 · Python 3.12

docs/developer/quality-assurance.md

@@ -100,11 +100,14 @@ For subprocess coverage investigations, mirror that command shape before
 deciding a fix. A plain local coverage run can miss subprocess data.
 Every Python version excludes the full BLAS/LAPACK real-library wrapper test
 while retaining general native-bundle coverage. The `Native Libraries`
-component runs the complete BLAS and LAPACK examples on Python 3.12. Those
-pytest invocations explicitly add each example's non-discovered
-`ci_full_surface.py`, reusing the session-scoped extension for complete
-root-export audits and runtime smoke calls instead of rebuilding the wrapper
-layer in a second process. A pull request may use the
+component runs the complete BLAS and LAPACK examples on Python 3.12. Each job
+step sources `build_all.sh`, which sources the exact `build_prik.sh` and
+`build_f2py.sh` sequences displayed in the user documentation, before starting
+pytest. Each f2py script reuses the native library from its PRIK script, and
+each explicitly selected `ci/full_surface.py` audit reuses the PRIK extension.
+The job therefore verifies the copyable commands without repeating native
+compilation or wrapper construction in a second process. A
+pull request may use the
 `ignore-real-library-wrappers` label to skip that expensive component without
 disabling the ordinary Python-version matrix.
 

docs/developer/repository-structure.md

@@ -56,8 +56,10 @@ through `prik/__init__.py`.
 | `tests/fortran/infrastructure/` | Internal cross-feature policy, wrapper-generation, compiler, and runtime frameworks with no honest public-capability owner. |
 | `tests/c/` | C input-language parsing, preprocessing, probe, semantic, CLI, and fixture evidence. |
 | `tests/shared/` | Language-neutral product architecture, documentation, naming, tools, type mapping, and utility checks. |
-| `examples/blas/test_*.py` | Dedicated real-library correctness documentation: explicit independent and PRIK/f2py differential validation for every Reference BLAS routine. |
-| `examples/lapack/test_*.py` | CI-only real-library correctness documentation: explicit independent and PRIK/SciPy/f2py validation for the reviewed double-precision routine inventory. |
+| `examples/blas/tests/test_*.py` | User-facing real-library correctness documentation: explicit independent and PRIK/f2py differential validation for every Reference BLAS routine. |
+| `examples/blas/ci/full_surface.py` | Maintainer-only complete BLAS export and smoke audit, selected explicitly by CI. |
+| `examples/lapack/tests/test_*.py` | User-facing real-library correctness documentation: explicit independent and PRIK/SciPy/f2py validation for the reviewed double-precision routine inventory. |
+| `examples/lapack/ci/full_surface.py` | Maintainer-only complete LAPACK export and smoke audit, selected explicitly by CI. |
 
 <!-- PRIK_C_DOCS_START
 | `tests/c/fixtures/parser/` | C parser-specific tests and fixture maintenance. |

docs/developer/source-map.md

@@ -50,8 +50,8 @@ change crosses ownership boundaries.
 | Immediate callback policy, typed adapters, and trampolines | `prik/semantics/wrapper_policy.py`, `prik/semantics/policy_completion.py`, `prik/wrapper_codegen/plan.py`, `prik/wrapper_codegen/planner.py`, `prik/wrapper_codegen/c/binding.py`, `prik/wrapper_codegen/fortran/bridge.py` | `docs/user/guide/callbacks.md`, `docs/user/reference/semantic-pyi-format.md` | `tests/fortran/callbacks/` |
 | Native compilation, binding support, and shared-library linking | `prik/pipeline/build.py`, `prik/compiling/compilers.py`, `prik/compiling/native_support.py` | `docs/user/reference/fortran-wrapper.md`, `docs/developer/build-system.md` | `tests/fortran/building_shared_library/end_to_end/test_runtime_compatibility.py`, `tests/fortran/building_shared_library/end_to_end/test_source_build_modes.py` |
 | Public Python exports | `prik/__init__.py` | `README.md`, `docs/user/reference/python-api.md` | `tests/fortran/source_parsing/parsing/test_public_entrypoints.py` |
-| Reference BLAS source ownership, inventory, and numerical validation | `examples/blas/routine_inventory.py`, `examples/blas/test_routine_coverage.py` | `examples/blas/README.md`, `docs/user/examples/blas-wrapper.md` | `examples/blas/test_*.py`, dedicated BLAS/LAPACK workflow |
-| Reference LAPACK source ownership, inventory, and numerical validation | `examples/lapack/routine_inventory.py`, `examples/lapack/test_routine_coverage.py` | `examples/lapack/README.md`, `docs/user/examples/lapack-wrapper.md` | `examples/lapack/test_*.py`, dedicated BLAS/LAPACK workflow |
+| Reference BLAS source ownership, inventory, and numerical validation | `examples/blas/routine_inventory.py`, `examples/blas/tests/test_routine_coverage.py` | `examples/blas/README.md`, `docs/user/examples/blas-wrapper.md` | `examples/blas/tests/test_*.py`, `examples/blas/ci/full_surface.py`, dedicated BLAS/LAPACK workflow |
+| Reference LAPACK source ownership, inventory, and numerical validation | `examples/lapack/routine_inventory.py`, `examples/lapack/tests/test_routine_coverage.py` | `examples/lapack/README.md`, `docs/user/examples/lapack-wrapper.md` | `examples/lapack/tests/test_*.py`, `examples/lapack/ci/full_surface.py`, dedicated BLAS/LAPACK workflow |
 | Source navigation documentation | `docs/developer/source-map.md`, `docs/developer/feature-to-code-map.md`, package README files | `docs/developer/source-map.md` | `tests/shared/docs/test_structure.py` |
 
 <!-- PRIK_C_DOCS_START

docs/developer/testing-strategy.md

@@ -120,35 +120,44 @@ Keep fixtures beside their final behavioral owner:
   `examples/lapack/native/`, shared by its correctness example and full-library
   integration.
 
-Generate build products and temporary contracts in pytest temporary
-directories. Check in generated `.pyi` only where exact generation text,
+Generate build products and temporary contracts in temporary directories.
+Check in generated `.pyi` only where exact generation text,
 imports, placement, or package shape is the invariant.
 
-For BLAS behavior, run `python3 -m pytest -q examples/blas` or one of its named
-test functions. The example-owned native builder compiles the sorted
-155-source implementation once; PRIK and f2py generate their own wrappers and
-link both to that artifact. `test_routine_coverage.py` audits the parsed source
-inventory, both export sets, visible named tests, and terminal outcomes. The
-separate full-library node remains available as opt-in
-`build_pyi_extension` and native-link integration evidence, but the dedicated
-CI lane explicitly adds `examples/blas/ci_full_surface.py` to the same pytest
-invocation and does not rebuild its wrappers afterward. Ordinary example runs
-do not discover that CI-only file.
-
-For LAPACK behavior, the dedicated lane runs
-`python3 -m pytest -q examples/lapack`. Its example-owned builder compiles the
-complete LAPACK corpus and required authoritative BLAS dependencies once;
-PRIK and f2py link their distinct wrappers to that same artifact while testing
-the reviewed 127-routine SciPy 1.18.0 `float64` inventory. The inventory audit fails on SciPy drift,
-missing sources or exports, missing explicitly named tests, and divergent
-documentation totals. CI explicitly adds `examples/lapack/ci_full_surface.py`
+For BLAS behavior, source `examples/blas/build_all.sh`, then run
+`python3 -m pytest -q examples/blas/tests` or one of its named test functions.
+The aggregate script sources the exact documented `build_prik.sh` and
+`build_f2py.sh` sequences. This compiles the sorted 155-source implementation
+once and builds each wrapper once; f2py links to the native artifact produced
+by the PRIK script.
+Documentation source markers require the displayed commands to remain
+byte-for-byte equal to the executed scripts. `test_routine_coverage.py` audits
+the parsed source inventory, both export sets, visible named tests, and terminal
+outcomes. The dedicated CI lane explicitly adds
+`examples/blas/ci/full_surface.py` to the same pytest invocation and does not
+rebuild its wrappers afterward. User-run correctness tests and maintainer-only
+audits therefore have separate directories.
+
+For LAPACK behavior, the dedicated lane sources `examples/lapack/build_all.sh`
+and then runs `python3 -m pytest -q examples/lapack/tests`. The aggregate
+script sources the exact documented `build_prik.sh` and `build_f2py.sh`
+sequences. The complete native corpus is compiled once, each wrapper is built
+once, and the f2py script reuses the native artifact produced by the PRIK
+script while testing the reviewed 127-routine SciPy 1.18.0 `float64`
+inventory. Documentation source markers keep the displayed commands equal to
+the executed scripts. The inventory audit fails on SciPy drift, missing
+sources or exports, missing explicitly named tests, and divergent
+documentation totals. CI explicitly adds `examples/lapack/ci/full_surface.py`
 to the same pytest invocation, reusing the complete PRIK extension to require
-all 2,064 root exports and run a non-inventory runtime smoke call. Ordinary
-example runs do not discover that file.
+all 2,064 root exports and run a non-inventory runtime smoke call. User-run
+correctness tests and maintainer-only audits have separate directories.
 
 The complete `examples/` tree is a copyable execution boundary. Example code
 may depend on an installed `prik` and its documented external toolchain, but it
-must not import repository-only helpers from `tests/`.
+must not import repository-only helpers from `tests/`. The workflow must source
+the documented build scripts through `build_all.sh` before starting pytest,
+rather than run a second build test that repeats native compilation or wrapper
+construction.
 
 ## Ownership discipline
 

docs/maintainer/roadmap/fortran-test-suite-cleanup-checklist.md

@@ -93,9 +93,6 @@ tests/
     building_shared_library/
       pipeline/
       end_to_end/
-        real_libraries/
-          blas/
-          lapack/
     source_parsing/
       parsing/
     source_preprocessing/
@@ -260,8 +257,8 @@ Register a structural marker for cross-feature selection:
 - [x] Shared tests import no language-owned helpers.
 - [x] Fortran and C tests import neither each other's helpers nor fixtures.
 - [x] Feature-local fixtures live with their owner. Minimized parser
-  regressions live under `source_parsing/parsing/`; BLAS and LAPACK live only under
-  `building_shared_library/end_to_end/real_libraries/`.
+  regressions live under `source_parsing/parsing/`; BLAS and LAPACK live only
+  under `examples/blas/` and `examples/lapack/`.
 - [x] `python -m pytest tests/fortran/arrays` runs every stage of the
   Arrays contract without collecting unrelated features.
 - [x] Every node below a feature's `end_to_end/` directory carries
@@ -1219,8 +1216,7 @@ Historical regression ownership after reduction:
 ### BLAS and LAPACK
 
 - [x] Move the real-library projects to
-  `examples/blas/` and
-  `tests/fortran/building_shared_library/end_to_end/real_libraries/lapack/`.
+  `examples/blas/` and `examples/lapack/`.
 - [x] Treat them only as full-pipeline evidence: build from the library sources,
   generate wrappers, compile/link, import the extension, and verify the public
   Python surface and representative runtime calls.

docs/maintainer/roadmap/semantic-pyi-wrapper-checklist.md

@@ -110,8 +110,8 @@ argument handoff from the native barrier action.
 
 Runtime wrapper tests are organized by stable subjects under
 `tests/wrapper/fortran/`: `build_from_source/`, `build_from_pyi/`,
-`multiple_files/`, `external_routines/`, `real_libraries/`,
-`edit_pyi_contracts/`, `arrays/`, `scalars/`, `function_calls/`,
+`multiple_files/`, `external_routines/`, `edit_pyi_contracts/`, `arrays/`,
+`scalars/`, `function_calls/`,
 `strings/`, `derived_types/`, `callbacks/`, `module_state/`,
 `runtime_behavior/`, `naming/`, and `layout_rules/`.
 
@@ -350,9 +350,9 @@ evidence lives in `tests/cli/`.
 
 ### Stage 7 — Library-Scale And Mixed-Bundle Evidence
 
-Real BLAS/LAPACK artifact-shape evidence lives in
-`tests/fortran/building_shared_library/end_to_end/real_libraries/test_full_libraries.py`. Native
-bundle, order, transitive-library, and failure-path evidence lives in
+Real BLAS/LAPACK artifact-shape evidence lives in `examples/blas/` and
+`examples/lapack/`. Native bundle, order, transitive-library, and failure-path
+evidence lives in
 `tests/fortran/building_shared_library/end_to_end/test_native_bundles.py`.
 
 - [x] Full real BLAS and LAPACK source corpora under `examples/blas/native/`
@@ -364,11 +364,11 @@ bundle, order, transitive-library, and failure-path evidence lives in
   helper declarations, imported symbols, and representative runtime behavior.
   Real-library evidence keeps no checked generated `.pyi`, edited `.pyi`, or
   source-free replay fixture.
-- [x] The full-library evidence builds each full root procedure contract with
-  `build_pyi_extension`, links it against a cached full native shared library,
-  imports every generated root procedure through the normalized Python names,
-  and checks that source stems and known generated helper declarations line up
-  with the shared native corpora.
+- [x] The example evidence builds each full root procedure contract through the
+  documented PRIK command, links it against one native shared library, imports
+  every generated root procedure through normalized Python names, and checks
+  that source stems and known generated helper declarations line up with the
+  shared native corpora.
 - [x] Full native BLAS/LAPACK object files are compiled once into a deterministic
   `.pytest_cache/prik/real-library-native` cache, archived once, and linked once
   into the shared libraries reused by repeated wrapper test runs; CI can move

docs/maintainer/roadmap/wrapper-plan-migration-checklist.md

@@ -561,13 +561,10 @@ route easier to exercise.
   generates a runtime wrapper must use the wrapper-plan route after cutover.
   Tests that only inspect documentation, layout, parsing, or `.pyi` generation
   may be `not-applicable` but must still pass.
-- During active migration, every local and GitHub Actions pytest invocation
-  excludes
-  `tests/fortran/building_shared_library/end_to_end/real_libraries/test_full_libraries.py`. Mark its BLAS
-  and LAPACK rows `deferred-real-library`; do not use either corpus for lane
-  parity or general migration verification. General native-bundle tests in
-  `test_stage7_native_bundles.py` remain active because they test linker/build
-  mechanics independently of the full BLAS/LAPACK corpora.
+- During active migration, ordinary pytest invocations exclude the full BLAS
+  and LAPACK example projects. Their dedicated lane owns library-scale
+  verification. General native-bundle tests remain active because they test
+  linker/build mechanics independently of the full corpora.
 
 ### Wrapper Test Migration Matrix
 
@@ -795,7 +792,6 @@ already covered by the new generator.
 | `tests/wrapper/fortran/naming/test_phase9_class_overloads.py::*` | reduced direct-plan constructor and method overload runtime proof | class-owned exact predicates; constructor ownership; no speculative calls | `wrapper-plan` |
 | `tests/wrapper/fortran/naming/test_visibility_naming.py::test_strict_wrapper_names_reject_python_name_fixes` | direct wrapper/build route | naming/visibility/dispatch; classes/methods/properties/overloads | `wrapper-plan` |
 | `tests/wrapper/fortran/naming/test_visibility_naming.py::test_visibility_and_default_python_name_fixing_policy[*]` | source/generated-.pyi parity or parametrized route | naming/visibility/dispatch; classes/methods/properties/overloads | `wrapper-plan` |
-| `tests/fortran/building_shared_library/end_to_end/real_libraries/test_full_libraries.py::*` | canonical full BLAS/LAPACK wrapper generation; BLAS runs locally and both exact nodes run together in the dedicated GitHub Actions job | external symbols/native linkage; build/compile/link orchestration; broad wrapper corpus | `wrapper-plan` |
 | `tests/fortran/building_shared_library/end_to_end/test_native_bundles.py::test_duplicate_native_definitions_report_linker_error` | direct wrapper/build route | scalar external symbols; linker failure propagation | `wrapper-plan` |
 | `tests/fortran/building_shared_library/end_to_end/test_native_bundles.py::test_imported_contracts_resolve_from_one_archive_or_shared_library[*]` | source/generated-.pyi parity or parametrized route | external symbols/native linkage; build/compile/link orchestration | `wrapper-plan` |
 | `tests/fortran/building_shared_library/end_to_end/test_native_bundles.py::test_incompatible_native_artifact_reports_linker_error` | non-generating: validation/failure-path assertion | external symbols/native linkage; build/compile/link orchestration | `not-applicable` |
@@ -4679,8 +4675,8 @@ Implement in these dependency-ordered waves:
 
 - [x] Reconcile every remaining `legacy` or `dual-route` matrix row by owning
   test area: `build_from_source`, `build_from_pyi`, `edit_pyi_contracts`,
-  `external_routines`, `multiple_files`, `naming`, `runtime_behavior`, and
-  `real_libraries`.
+  `external_routines`, `multiple_files`, `naming`, `runtime_behavior`, and the
+  full BLAS/LAPACK examples.
 - [x] Group remaining rows into dependency-ordered waves by their actual
   unsupported owner paths. Do not implement a broad test directory as one
   special case and do not add per-test backend fallbacks.