Devel doc

.githooks/pre-push

@@ -12,7 +12,7 @@ DOCUMENTATION_SMOKE_TESTS = (
     "tests/docs/test_user_content.py",
 )
 WRAPPER_SMOKE_TEST = (
-    "tests/fortran/building_shared_library/end_to_end/test_source_build_modes.py::"
+    "tests/fortran/infrastructure/building/end_to_end/test_source_build_modes.py::"
     "test_fortran_wrapper_default_module_name_does_not_collide_with_root_function"
 )
 REQUIRED_TESTS = ("tests/tools", "tests/workflows")

.github/workflows/merge-validation.yml

@@ -440,7 +440,7 @@ jobs:
           done
 
   native-libraries:
-    name: BLAS + LAPACK + FFTPACK + MINPACK · Ubuntu 24.04 · Python 3.12
+    name: BLAS + LAPACK + FFTPACK + MINPACK + BSPLINE-FORTRAN · Ubuntu 24.04 · Python 3.12
     needs: [unit-tests, unit-tests-macos]
     if: >-
       ${{ !contains(github.event.pull_request.labels.*.name, 'ignore-real-library-wrappers') }}
@@ -537,6 +537,13 @@ jobs:
         run: |
           source examples/minpack/build_all.sh
           python -m pytest -q examples/minpack/tests
+      - name: Run BSPLINE-FORTRAN full-surface audit
+        env:
+          PYTHONPATH: .
+          HYPOTHESIS_PROFILE: ci
+        run: |
+          source examples/bspline/build_all.sh
+          python -m pytest -q examples/bspline/tests
 
   documentation-benchmark:
     name: Documentation performance benchmark · Ubuntu 24.04 ARM64 · Python 3.12

.github/workflows/real-libraries.yml

@@ -111,3 +111,10 @@ jobs:
         run: |
           source examples/minpack/build_all.sh
           python -m pytest -q examples/minpack/tests
+      - name: Run BSPLINE-FORTRAN abstract-hierarchy and interpolation audit
+        env:
+          PYTHONPATH: .
+          HYPOTHESIS_PROFILE: ci
+        run: |
+          source examples/bspline/build_all.sh
+          python -m pytest -q examples/bspline/tests

AGENTS.md

@@ -80,6 +80,24 @@ the selected plan requires a genuinely new emitted-code mechanism; those
 generators should otherwise keep reusing and dispatching existing planned
 paths.
 
+To answer an ABI question, or to decide whether something belongs in the
+binding or in the Fortran bridge, first ask: **how would this work for a
+`bind(C)` procedure, where there is no bridge at all?** A direct entrypoint has
+only the binding and the user's C ABI symbol, so whatever the direct route must
+do is binding-owned by definition. The bridge then owns exactly the remainder:
+the work that makes an ordinary non-`bind(C)` procedure reachable through that
+same completed plan. Deriving the boundary this way keeps one shared entrypoint
+contract for both routes instead of two parallel designs.
+
+The question is still decisive when the form cannot be `bind(C)` at all. A
+Fortran type that no interoperable interface can declare — a deferred-length
+`character(len=:)` dummy, for example, which the standard rejects in a
+`bind(C)` interface because character dummies there must have length 1 — proves
+that a generated Fortran adapter is mandatory rather than optional, and names
+what that adapter has to construct: the non-interoperable local the native
+dummy requires. Record that reasoning with the completed policy so the bridge
+implements a decided mechanism rather than rediscovering it.
+
 After every implementation task, the final summary must include a breakdown of
 the stages that actually changed. Relevant stages include parsing, semantic IR
 construction, post-IR policy completion, wrapper planning/direct lowering, binding
@@ -98,7 +116,7 @@ Changes limited to wrapper planning, direct bridge/binding lowering, or native
 compilation should use the focused owners under
 `tests/fortran/infrastructure/codegen/`, feature-local
 `tests/fortran/*/codegen/` directories, and
-`tests/fortran/building_shared_library/compiling/` as applicable. Include the
+`tests/fortran/infrastructure/building/compiling/` as applicable. Include the
 relevant end-to-end feature tests whenever a generated or compiled mechanism
 changes; run a broader suite when behavior spans multiple stages.
 Do not run LAPACK wrapper tests locally unless the user explicitly asks for them. Local verification may run everything else, including BLAS-only real-library tests; leave LAPACK coverage to GitHub Actions by default.

README.md

@@ -59,7 +59,7 @@ python3 -m prik points.f90 --out geometry
 
 Create `points.f90`:
 
-<!-- prik-doc-source: tests/fortran/building_shared_library/end_to_end/fixtures/native/home_points.f90 -->
+<!-- prik-doc-source: tests/fortran/infrastructure/building/end_to_end/fixtures/native/home_points.f90 -->
 ```fortran
 module points
   implicit none
@@ -210,13 +210,29 @@ charts below come from the latest successfully deployed benchmark snapshot.
 
 ## Current limitations
 
-PRIK does not yet support:
+PRIK rejects these forms rather than wrapping them unsafely. Most fail before
+code generation with a diagnostic naming the boundary and the reason.
 
-- arrays of derived types;
-- procedure pointers, including procedure-pointer module variables and callbacks
-  retained after the wrapped call; or
-- polymorphic outputs, mutable polymorphic arguments, polymorphic arrays,
-  unlimited polymorphism (`class(*)`), abstract types, and deferred bindings.
+**Types and arrays**
+
+- arrays of derived types, and assumed-type `type(*)` arrays;
+- character arrays that cannot be represented as a fixed-width NumPy bytes
+  dtype, and `allocatable` and `pointer` character *fields*.
+- real and complex storage wider than the target's `long double`. NumPy's
+  `longdouble` is whatever the target C compiler provides, so `real(10)` and C
+  `long double` are supported while IEEE quad `real(16)` is refused on a target
+  whose `long double` is x87 extended precision. The diagnostic names the
+  measured mantissa width on both sides.
+
+**Procedures and polymorphism**
+
+- procedure-pointer module variables, and
+  callbacks retained after the wrapped call returns;
+- polymorphic outputs, mutable polymorphic arguments, polymorphic
+  `allocatable` and `pointer` scalars, and unlimited polymorphism (`class(*)`).
+
+The [language feature matrix](https://pynumlab.github.io/prik/user/language-support/feature-matrix/)
+records the full support status of every feature with its evidence.
 
 ## Installation & Quick Start
 
@@ -393,9 +409,7 @@ notice when redistributed.
 - **[User Guide](https://pynumlab.github.io/prik/user/guide/)** — Data types, functions, modules, arrays, derived types, callbacks, ownership, and runtime behavior
 - **[Changelog](CHANGELOG.md)** — User-visible changes by release
 <!--
-- **[Tutorials](docs/user/tutorials/index.md)** — Step-by-step walkthroughs
 - **[CLI Reference](docs/user/reference/cli-commands.md)** — Complete command-line documentation
 - **[Language Support](docs/user/language-support/index.md)** — What is supported, partially supported, or planned
 - **[FAQ](docs/user/faq/index.md)** — Concise answers to common questions
-- **[Troubleshooting](docs/user/troubleshooting/index.md)** — Solutions for installation, compiler, build, runtime, and platform issues
 -->

docs/developer/deferred/c-parser.md

@@ -19,8 +19,8 @@ Status: current reference for the partial C frontend. The `prik.parsers.c`
 package, typed parser models, explicit C CLI parse path, raw directive
 metadata, compiler-assisted preprocessing, source-location remapping, project
 indexes, legacy parser schema snapshots, C standard-type probe, first semantic IR conversion
-subset, semantic conversion path, and starter exact-contract C `.pyi`
-generation are implemented.
+subset, semantic conversion path, starter exact-contract C `.pyi` generation,
+and the initial direct-only primitive C wrapper lane are implemented.
 PRIK_C_DOCS_END -->
 
 <!&#45;&#45; PRIK_C_DOCS_START
@@ -177,6 +177,9 @@ PRIK_C_DOCS_END &#45;&#45;>
   functions, const/mutable pointer storage contracts, declared arrays,
   structs/opaque structs, enums, numeric macro constants, local typedef
   chains, standard-type probe facts, and explicit semantic conversion errors
+- direct-only C wrapper builds for target-probed primitive values, `void`, and
+  author-selected one-level primitive-pointer scalar or NumPy contracts;
+  unsupported C forms receive a pre-planning diagnostic
 PRIK_C_DOCS_END &#45;&#45;>
 
 <!&#45;&#45; PRIK_C_DOCS_START
@@ -850,8 +853,8 @@ Useful local checks for the parse-only frontend:
 ```bash
 python -m prik tests/c/fixtures/native/general/math_api.h &#45;&#45;language c &#45;&#45;parse &#45;&#45;json
 python tests/c/fixtures/parser/generate_c_parser_goldens.py tests/c/fixtures/native/general/math_api.h
-pytest -q tests/c/parsing/test_c_declarations_and_declarators.py
-pytest -q tests/c/parsing/test_c_fixture_suite.py
+pytest -q tests/c/infrastructure/parsing/test_c_declarations_and_declarators.py
+pytest -q tests/c/infrastructure/parsing/test_c_fixture_suite.py
 pytest -q tests/c
 pytest -q
 ```
@@ -861,30 +864,32 @@ Focused test files by implementation area:
 
 <!&#45;&#45; PRIK_C_DOCS_START
 - Lexer, comments, continuations, raw directive handling:
-  `tests/c/parsing/test_c_lexer_preprocessor.py`
+  `tests/c/infrastructure/parsing/test_c_lexer_preprocessor.py`
 - Declaration specifiers, qualifiers, declarators, arrays, pointers,
   callbacks, and variables:
-  `tests/c/parsing/test_c_declarations_and_declarators.py`
+  `tests/c/infrastructure/parsing/test_c_declarations_and_declarators.py`
 - Function prototypes and definitions:
-  `tests/c/parsing/test_c_functions.py`
-- Structs, unions, enums, typedefs, and aggregate members:
-  `tests/c/parsing/test_c_structs_unions_enums_typedefs.py`
+  `tests/c/functions/parsing/test_c_functions.py`
+- Structs, unions, typedefs, and aggregate members:
+  `tests/c/records/parsing/test_c_structs_unions_typedefs.py`
+- Enum declarations and enumerator values:
+  `tests/c/enumerations/parsing/test_c_enum_syntax.py`
 - Project assembly, include graph facts, typedef/tag resolution, and
   redeclarations:
-  `tests/c/parsing/test_c_project_resolution.py`
+  `tests/c/infrastructure/parsing/test_c_project_resolution.py`
 - Compiler extension tolerance and diagnostics:
-  `tests/c/parsing/test_c_compiler_extensions.py`
+  `tests/c/infrastructure/parsing/test_c_compiler_extensions.py`
 - Corpus/third-party-style fixtures:
-  `tests/c/parsing/test_c_corpus.py`
+  `tests/c/infrastructure/parsing/test_c_corpus.py`
 - Project golden fixtures:
-  `tests/c/parsing/test_c_fixture_suite.py`
+  `tests/c/infrastructure/parsing/test_c_fixture_suite.py`
 - Parser JSON shape:
-  `tests/c/parsing/test_c_json_sanity.py`
+  `tests/c/infrastructure/parsing/test_c_json_sanity.py`
 - Fatal parser diagnostic goldens:
-  `tests/c/parsing/test_c_error_fixture_suite.py`
+  `tests/c/infrastructure/parsing/test_c_error_fixture_suite.py`
 - Public API and developer tutorial:
-  `tests/c/parsing/test_c_public_api_skeleton.py` and
-  `tests/c/parsing/test_c_parser_developer_tutorial.py`
+  `tests/c/infrastructure/parsing/test_c_public_api_skeleton.py` and
+  `tests/c/infrastructure/execution_examples/test_c_parser_developer_tutorial.py`
 PRIK_C_DOCS_END &#45;&#45;>
 
 <!&#45;&#45; PRIK_C_DOCS_START
@@ -962,7 +967,7 @@ PRIK_C_DOCS_END &#45;&#45;>
 <!&#45;&#45; PRIK_C_DOCS_START
 For an executable maintainer walkthrough of the parser gateway and
 preprocessed source path, read
-`tests/c/parsing/test_c_parser_developer_tutorial.py`.
+`tests/c/infrastructure/execution_examples/test_c_parser_developer_tutorial.py`.
 PRIK_C_DOCS_END &#45;&#45;>
 
 ## CLI Workflow
@@ -1054,7 +1059,8 @@ source path or source text
   -> CParser._assemble_project(...) or parse_c_project(...)
   -> CProject indexes and cross-file resolution facts
   -> semantics.c2ir conversion
-  -> policy completion and `.pyi`; a C-input runtime wrapper backend comes later
+  -> starter `.pyi` extraction, or completed direct-only primitive C policy
+  -> direct binding generation, C compilation/linking, import, and call
 ```
 PRIK_C_DOCS_END &#45;&#45;>
 
@@ -1069,6 +1075,10 @@ Keep these boundaries:
   they are not recursive parse roots unless supplied by the user.
 - Semantic conversion is the first place where parser-native facts become the
   shared language-neutral model.
+- The runtime lane is deliberately narrow and generates no C adapter.
+  Aggregates, callbacks, variadics, pointer results, nullable or retained
+  pointers, multi-level pointers, `volatile`/atomic access, and unsupported
+  calling conventions fail before planning.
 
 The parser algorithm should remain grammar-style:
 
@@ -1113,13 +1123,13 @@ Testing should grow in this order:
 
 Executable references:
 
-- Shared CLI behavior: `tests/fortran/command_line_interface/pipeline/`
+- Shared CLI behavior: `tests/fortran/infrastructure/cli/pipeline/`
 
 <!&#45;&#45; PRIK_C_DOCS_START
-- C parser walkthrough: `tests/c/parsing/test_c_parser_developer_tutorial.py`
-- C declaration coverage: `tests/c/parsing/test_c_declarations_and_declarators.py`
-- C project/golden workflow: `tests/c/parsing/test_c_fixture_suite.py`
-- C semantic handoff: `tests/c/semantics/conversion/`
+- C parser walkthrough: `tests/c/infrastructure/execution_examples/test_c_parser_developer_tutorial.py`
+- C declaration coverage: `tests/c/infrastructure/parsing/test_c_declarations_and_declarators.py`
+- C project/golden workflow: `tests/c/infrastructure/parsing/test_c_fixture_suite.py`
+- C semantic handoff: `tests/c/*/semantics/`
 PRIK_C_DOCS_END &#45;&#45;>
 
 Fixture layout should be separate from Fortran:
@@ -1159,7 +1169,7 @@ that Linux reference environment.
 The fixture suite also checks same-stem grouping order and representative raw
 preprocessing failures.
 Fatal diagnostic goldens are regenerated with
-`C_PARSER_UPDATE_GOLDENS=1 PYTHONPATH=. pytest -q tests/c/parsing/test_c_error_fixture_suite.py`.
+`C_PARSER_UPDATE_GOLDENS=1 PYTHONPATH=. pytest -q tests/c/infrastructure/parsing/test_c_error_fixture_suite.py`.
 The standalone error generator remains available for targeted refreshes.
 By policy, a paired project records source-to-header include edges but parses
 each supplied `.c`, `.h`, or `.i` member separately; include traversal is not