codex: correct release documentation and condense changelog

Author: saidctb

CHANGELOG.md

@@ -230,15 +230,15 @@ class Point:
     @native_call([Pass(), Addr(Arg(0)), Addr(Arg(1))])
     def translate(self, dx: Float64, dy: Float64) -> None: ...
 
+    @bind("norm_squared")
     @native_call([Pass()])
     def norm_squared(self) -> Float64: ...
 ```
 
-`@bind("move")` maps the Python-facing `translate` method to the native
-`move` procedure. `norm_squared` needs no `@bind` because its Python and
-native names already match. `Pass()` supplies the receiver (`self`) to the
-native call; `Addr(Arg(...))` passes the remaining arguments by address as
-required by the native calling convention.
+Both methods call module procedures, so each uses `@bind`: `translate` calls
+`move`, and `norm_squared` calls `norm_squared`. Without `@bind`, a method calls
+a type-bound procedure of its own name. `Pass()` supplies the receiver (`self`)
+to the native call; `Addr(Arg(...))` passes the remaining arguments by address.
 
 Build from the contract:
 

docs/index.md

@@ -187,51 +187,12 @@ python3 -m pytest -q examples/fortran/prima/tests
 The suite checks a numerical result for each of the five exposed solvers,
 exact API selection, and callback behavior when optional arguments are
 present or omitted. It is not an exhaustive solver-option or constraint
-suite.
+suite. The [test file](../../../../examples/fortran/prima/tests/test_solvers.py)
+shows each solver case and checks COBYLA's optional progress callback.
 
 ---
 
-## 5. See how results are validated
-
-For the quadratic in section 3, the known minimizer `(1, -2)` is the primary
-numerical check. The COBYLA test below also confirms that its optional
-progress callback receives the expected argument shapes. The test file's
-`_objective` helper evaluates `(x[0] - 1)^2 + (x[1] + 2)^2`:
-
-<!-- prik-doc-source: examples/fortran/prima/tests/test_solvers.py::test_cobyla_runs_with_every_optional_callback_dummy_present -->
-```python
-def test_cobyla_runs_with_every_optional_callback_dummy_present(prima):
-    x = np.asfortranarray(np.array([3.0, 0.0], dtype=np.float64))
-    observed = []
-
-    def objective_and_constraints(values, f, constraints):
-        _objective(values, f)
-
-    def progress(values, f, nf, tr, cstrv, nlconstr, terminate):
-        observed.append((f, nf, tr, cstrv, nlconstr.shape, terminate.shape))
-
-    prima.cobyla_mod.cobyla(
-        objective_and_constraints,
-        np.int32(0),
-        x,
-        maxfun=np.int32(100),
-        callback_fcn=progress,
-    )
-
-    np.testing.assert_allclose(x, np.array([1.0, -2.0]), atol=2.0e-3, rtol=0.0)
-    assert observed
-    assert observed[-1][4:] == ((0,), ())
-```
-
-SciPy 1.18's
-[COBYLA implementation](https://docs.scipy.org/doc/scipy/reference/optimize.minimize-cobyla.html)
-also comes from PRIMA, so the optional SciPy test is a cross-interface parity
-check rather than an independent algorithmic oracle. Both results are also
-checked against the known minimizer `(1, -2)`.
-
----
-
-## 6. Run focused examples
+## 5. Run focused examples
 
 After building the extension, run one solver test or the optional SciPy
 comparison:
@@ -242,10 +203,9 @@ python3 -m pip install "scipy==1.18.0"
 python3 -m pytest -q examples/fortran/prima/tests/test_solvers.py::test_cobyla_agrees_with_scipy_on_a_quadratic
 ```
 
-The checked-in test file is a starting point for your own cases: add a
-`test_*` function there, or a `test_*.py` file beside it. The shared `prima`
-fixture imports the built extension. Change the objective, initial `x`, and
-expected result, then run your new test with the same pytest command.
+SciPy's COBYLA also uses PRIMA, so this is a cross-interface comparison; the
+known minimizer remains the independent numerical check. To test your own
+problem, add a case beside the checked-in tests and run it with pytest.
 
 - Solver and callback examples →
   [`test_solvers.py`](../../../../examples/fortran/prima/tests/test_solvers.py)

docs/user/examples/fortran/prima-wrapper.md

@@ -232,7 +232,8 @@ Fortran modules and their storage do not move; only the Python API changes.
 Publishing a module variable in more than one namespace gives every name the
 same live storage, so a write, allocation, pointer association, or derived
 object mutation through one name is visible through all of them. Parameters
-remain read-only constants in every namespace.
+start with the same value in every namespace, but assigning one Python name
+does not change the others or the Fortran parameter.
 
 Wildcard imports never use import order to resolve a collision. If both
 modules export the same name, the wrapper build fails and asks for an explicit

docs/user/guide/wrapping-modules.md

@@ -72,7 +72,7 @@ where they apply.
 | Scalar character arguments, results, and fields | Supported | [Strings](../guide/strings.md) | [Character argument tests](../../../tests/fortran/strings/end_to_end/test_character_boundaries.py), [edge-case tests](../../../tests/fortran/strings/end_to_end/test_character_edge_cases.py) | Character arrays use fixed-width NumPy bytes dtype. Scalar `character` `allocatable` and `pointer` values are supported for `intent(in)`, `intent(out)`, `intent(inout)`, and function results, at deferred (`len=:`) and declared (`len=n`) length; a mutable dummy returns the value the procedure left behind, or `None`. PRIK frees the target it allocated for the call while it can still prove that identity, but never a target the procedure reassociated or the library owns; a procedure that returns a fresh allocation each call leaks unless it frees its own. |
 | Character arrays and caller-supplied deferred-length character storage | Supported | [Strings](../guide/strings.md) | [Character edge tests](../../../tests/fortran/strings/end_to_end/test_character_edge_cases.py) | Character arrays use fixed-width NumPy bytes dtype, whose width each accessor reports from the Fortran declaration. `character(kind=selected_char_kind('ISO_10646'))` uses `UString` contracts and NumPy `U<n>` storage on compilers that provide the kind. Scalar `character` `allocatable` and `pointer` values work for every intent and as function results. A mutable `pointer` dummy that the native procedure reassociates without deallocating orphans the target the adapter allocated for that call. |
 | Scalar kind coverage | Supported | [Data types](../guide/data-types.md) | [Scalar kind tests](../../../tests/fortran/data_types/end_to_end/test_primitive_scalar_runtime.py) | Real and complex storage wider than the target's `long double` is blocked. Logical scalars use Python `bool`; arrays use their documented NumPy dtype. |
-| Multi-source builds, Makefiles, verbose mode, and output placement | Supported | [Building the shared library](../guide/building-shared-library.md) | [Multi-source tests](../../../tests/fortran/infrastructure/building/end_to_end/test_multi_source_builds.py), [compiler verbose tests](../../../tests/fortran/infrastructure/building/compiling/test_compiler_verbose.py) | Wrapped project sources compile in dependency order derived from their module/`use` graph, falling back to the given order when a compiled source was not parsed. PRIK does not discover sources you did not name, prebuilt module paths, or external libraries. |
+| Multi-source builds, module-source discovery, Makefiles, verbose mode, and output placement | Supported | [Building the shared library](../guide/building-shared-library.md), [CLI source discovery](../reference/cli-commands.md#input-selection) | [Multi-source tests](../../../tests/fortran/infrastructure/building/end_to_end/test_multi_source_builds.py), [module discovery tests](../../../tests/fortran/modules/end_to_end/test_module_source_discovery.py), [compiler verbose tests](../../../tests/fortran/infrastructure/building/compiling/test_compiler_verbose.py) | PRIK orders sources by module dependencies and can discover used module sources under `--module-source-dir`. External libraries and prebuilt module directories remain explicit inputs. |
 | Visibility, naming, keyword escaping, and collision policy | Supported | [Generic interfaces](../guide/generic-interfaces.md#key-rules) | [Visibility/naming tests](../../../tests/fortran/infrastructure/semantic_pyi/contracts/exports_and_modules/end_to_end/test_visibility_naming.py) | Strict mode rejects names that default mode can normalize. |
 | Immediate call-scoped Python callbacks | Supported | [Callbacks](../guide/callbacks.md) | [Callback plan tests](../../../tests/fortran/callbacks/codegen/test_callback_planning.py), [scalar callback tests](../../../tests/fortran/callbacks/end_to_end/test_scalar_callbacks.py), [array callback tests](../../../tests/fortran/callbacks/end_to_end/test_array_callbacks.py), [combined shape tests](../../../tests/fortran/callbacks/end_to_end/test_supported_callback_shapes.py), [optional callback tests](../../../tests/fortran/callbacks/end_to_end/test_optional_callbacks.py) | Direct wrapper-plan generation supports entering-thread callbacks only; an optional callback may be omitted or `None`. Stored, asynchronous, or cross-thread callbacks are unsupported. |
 | Runtime error projection, GIL policy, recursion, OpenMP path, and GNU ABI checks | Supported | [Error handling](../guide/error-handling.md) | [Status projection runtime](../../../tests/fortran/error_handling/end_to_end/test_status_projection.py), [status and GIL lowering](../../../tests/fortran/error_handling/codegen/test_status_error_lowering.py), [recursion tests](../../../tests/fortran/error_handling/end_to_end/test_runtime_recursion.py), [OpenMP tests](../../../tests/fortran/error_handling/end_to_end/test_openmp_runtime.py), [ABI tests](../../../tests/fortran/infrastructure/building/end_to_end/test_runtime_compatibility.py) | OpenMP and ABI evidence is compiler/platform-specific; callers still own native synchronization. |
@@ -127,7 +127,7 @@ documented diagnostic-stage exception below.
 | --- | --- | --- | --- | --- |
 | Unproved pointer lifetime and ownership-changing operations | Unsupported | [Pointer safety](../guide/pointers.md#safety-checklist) | [Pointer policy tests](../../../tests/fortran/pointers/policy/test_pointer_ownership_policy.py), [pointer handle tests](../../../tests/fortran/pointers/end_to_end/test_pointer_handles.py) | Native targets must outlive every handle use; allocation, target deallocation, resize, and writable reassociation require explicit completed policy. |
 | Persistent callbacks and procedure pointers | Unsupported | [Callback limitations](../guide/callbacks.md#important-limitations) | [Callback policy tests](../../../tests/fortran/callbacks/policy/test_callback_policy.py), [scalar callback tests](../../../tests/fortran/callbacks/end_to_end/test_scalar_callbacks.py) | Callbacks are valid only during the wrapped call. |
-| Advanced multi-source dependency discovery and external-library integration | Unsupported | [Multiple source files](../guide/building-shared-library.md#multiple-source-files) | [Multi-source tests](../../../tests/fortran/infrastructure/building/end_to_end/test_multi_source_builds.py) | PRIK does not discover sources you did not name, prebuilt module search paths, or external libraries. Dependency ordering among the sources it parses is supported. |
+| Automatic discovery of external libraries and prebuilt module directories | Unsupported | [Building the shared library](../guide/building-shared-library.md) | [Module discovery tests](../../../tests/fortran/modules/end_to_end/test_module_source_discovery.py) | `--module-source-dir` finds Fortran sources; supply prebuilt module paths and libraries explicitly. |
 | Blocked array forms | Unsupported | [Arrays](../guide/arrays.md) | [Array semantic tests](../../../tests/fortran/arrays/semantics/test_array_semantics.py), [diagnostics](../reference/diagnostic-codes.md) | Arrays of derived types and character arrays not representable as fixed-width bytes need missing runtime contracts. |
 | Unsupported polymorphic forms | Unsupported | [Inheritance limits](../guide/wrapping-derived-types.md#inheritance-and-polymorphic-input-dispatch) | [Inheritance tests](../../../tests/fortran/derived_types/codegen/test_class_surfaces.py) | Results, mutable dummies, arrays, polymorphic allocatable/pointer scalars, and `class(*)` are blocked. Abstract types and deferred bindings are supported. |
 | Ambiguous or incomplete constructor overload sets | Unsupported | [Constructor limitations](../guide/wrapping-derived-types.md#custom-constructor) | [Constructor semantic tests](../../../tests/fortran/infrastructure/semantic_pyi/contracts/functions_and_classes/semantics/test_method_and_constructor_contracts.py), [class-plan validation tests](../../../tests/fortran/infrastructure/semantic_pyi/contracts/functions_and_classes/policy/test_class_surface_policy.py) | Candidates must have distinguishable exact runtime signatures and compatible native-owner lifecycles. A Fortran `interface <typename>` is wrapped as the type's overloaded constructor. |

docs/user/language-support/feature-matrix.md

@@ -75,10 +75,12 @@ native module. The [`.pyi` format reference](../reference/pyi-format.md#source-t
 contrasts that package with C's single-file output.
 
 Suffix matching is case-insensitive, and fixed-form and free-form sources can
-be mixed in one build. For multi-source projects, PRIK orders named sources
-from their module dependency graph. It does not discover files or external
-libraries that were not supplied explicitly; see [Building the Shared
-Library](../guide/building-shared-library.md).
+be mixed in one build. For multi-source projects, PRIK orders sources by their
+module dependency graph. Pass `--module-source-dir` to discover the sources of
+used modules under named directories; external libraries and their module
+directories must still be supplied explicitly. See
+[CLI commands](../reference/cli-commands.md#input-selection) and
+[Building the Shared Library](../guide/building-shared-library.md).
 
 The Python-facing entry points are:
 

docs/user/language-support/fortran-support.md

@@ -150,7 +150,8 @@ Type-bound and magic methods follow the same rules:
 
 - keep a concrete native procedure declaration;
 - place `self` with `Pass()` when the native call needs it;
-- use `@bind(...)` when the Python and native names differ; and
+- use `@bind("procedure")` to call a module procedure, or a class-qualified
+  `@bind("Class.binding")` for a differently named type-bound procedure; and
 - use `@overload(...)` when one Python method accepts several native
   signatures.
 

docs/user/reference/pyi-contracts/functions-and-classes.md

@@ -551,17 +551,20 @@ keyword-only, variadic, and untyped parameters are rejected outside the
 generated constructor form.
 
 Methods use the same rules plus an untyped `self`. `Pass()` places that object
-in an explicit native argument list. `@bind(...)` is needed only when the
-Python declaration and native callable names differ. For an `@overload(...)`
-declaration the native callable defaults to the linked specific, not the
-Python name; see [Generic Procedure Overloads](#generic-procedure-overloads).
+in an explicit native argument list. In a Fortran contract, a method without
+`@bind` calls the type-bound procedure of its own name; `@bind("procedure")`
+calls a module procedure, even when the names match; and
+`@bind("Class.binding")` selects a differently named type-bound procedure. For
+an `@overload(...)` declaration the native callable defaults to the linked
+specific, not the Python name; see
+[Generic Procedure Overloads](#generic-procedure-overloads).
 
 ### Function And Method Decorators
 
 | Decorator | Valid target | Language and meaning |
 | --- | --- | --- |
 | `@private` | Function or method | Shared: declaration remains available to contract dependencies but is not exported. |
-| `@bind("symbol")` | Function, method, constructor, prototype, or destructor | Shared: select a different native name. A module-level Fortran procedure is called through the native module the contract module names, so the symbol may be any procedure or generic that module provides, including one it imports. |
+| `@bind("symbol")` | Function, method, constructor, prototype, or destructor | Shared: select a native target. A plain Fortran method target calls a module procedure; a class-qualified target calls a type-bound procedure. A module-level Fortran target may be any procedure or generic that module provides, including one it imports. |
 | `@native_abi("c")` | Function, method, or prototype | Fortran only: original declaration is `bind(C)`. |
 | `@standalone` | Module-level function | Fortran only: native procedure is outside a module. |
 | `@native_call([...], result=...)` | Function, method, or constructor | Shared: state the complete native argument order and optional native result mapping. |

docs/user/reference/pyi-format.md

@@ -59,8 +59,9 @@ if rank == 0:
 
 You build two APIs: the **wrapped API** (`prik_openmpi_f08`), generated by
 PRIK, and the **Python API** (`prik_mpi.py`), a few lines of Python on top of
-it. Both are faster than mpi4py on small messages; see
-[Compare call times](#compare-call-times).
+it. In the measured setup, both had lower median times than mpi4py for small
+`Allreduce` calls; see [Compare call times](#compare-call-times) for the other
+operations and the test environment.
 
 ## What you need