improve coverage and remove dead branches

Author: saidctb

README.md

@@ -520,40 +520,6 @@ X2PY_C_DOCS_END -->
 For native projects with macros, includes, or target flags, use the
 compiler-preprocessed CLI path or an equivalent preprocessing configuration.
 
-## Supported Scope
-
-x2py preserves wrapper-relevant declarations, signatures, types, source
-locations, include/use relationships, diagnostics, and semantic metadata.
-Current support includes:
-
-- free-form and fixed-form Fortran, procedures, modules, derived types,
-  imports, arrays, and wrapper-relevant declaration attributes;
-- language-neutral semantic IR and editable `.pyi` interfaces;
-- compiled Python extensions from one or more ordered fixed-form or free-form
-  Fortran sources, with an optional GNU Make build;
-- documented runtime wrapper behavior for scalar and array calls, strings,
-  module state, derived types, generic interfaces, optional and output
-  arguments, and immediate call-scoped Python callbacks. The
-  [language feature matrix](docs/user/language-support/feature-matrix.md) is the
-  authoritative support-status summary.
-
-<!-- X2PY_C_DOCS_START
-- compiled CPython extensions from one or more ordered fixed-form or free-form
-  Fortran sources, including generated Fortran/C bridges and an optional GNU
-  Make build;
-- C declarations and definitions, variables, typedefs, aggregates, enums,
-  pointers, arrays, function pointers, includes, and preprocessing facts;
-X2PY_C_DOCS_END -->
-
-<!-- X2PY_C_DOCS_START
-Runtime wrapper generation from user C inputs is not implemented yet. It will
-reuse the shared semantic contracts after the C backend and its ownership,
-ABI, and runtime tests are complete.
-X2PY_C_DOCS_END -->
-
-x2py is not a full compiler frontend. It does not silently infer pointer
-ownership, callback lifetime, ABI shims, or Python-visible projections.
-
 ## Documentation
 
 - **[Documentation](https://pynumlab.github.io/x2py/)** — Complete published documentation

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

@@ -594,7 +594,7 @@ summary, the exhaustive matrix, and the test tree disagree.
 
 | Status | Collected nodes |
 | --- | ---: |
-| `wrapper-plan` | 366 |
+| `wrapper-plan` | 369 |
 | `dual-route` | 0 |
 | `legacy` | 0 |
 | `not-applicable` | 76 |
@@ -749,6 +749,9 @@ already covered by the new generator.
 | `tests/wrapper/fortran/external_routines/test_external_procedures.py::test_free_form_standalone_external_runtime_parity[*]` | source/generated-.pyi parity or parametrized route | scalar external symbol; explicit bridge interface | `wrapper-plan` |
 | `tests/wrapper/fortran/external_routines/test_external_procedures.py::test_generated_external_contracts_are_non_empty_root_fragments` | direct wrapper/build route | external symbols/native linkage | `wrapper-plan` |
 | `tests/wrapper/fortran/external_routines/test_external_procedures.py::test_handwritten_c_order_flat_contract_passes_rank_preserving_bridge_view` | direct wrapper/build route | external symbols/native linkage; ordinary arrays | `wrapper-plan` |
+| `tests/wrapper/fortran/external_routines/test_external_procedures.py::test_handwritten_fortran_order_flat_contract_flattens_the_final_python_axes` | direct wrapper/build route | external symbols/native linkage; flat arrays; scalar storage | `wrapper-plan` |
+| `tests/wrapper/fortran/external_routines/test_external_procedures.py::test_external_allocatable_argument_accepts_a_caller_created_handle` | direct wrapper/build route | external symbols/native linkage; native allocatable descriptors | `wrapper-plan` |
+| `tests/wrapper/fortran/external_routines/test_external_procedures.py::test_optional_flat_contracts_preserve_present_and_absent_calls` | direct wrapper/build route | optional/presence; F-order and C-order flat arrays | `wrapper-plan` |
 | `tests/wrapper/fortran/external_routines/test_external_procedures.py::test_module_procedure_bridge_uses_native_module_scope` | direct wrapper/build route | external symbols/native linkage | `wrapper-plan` |
 | `tests/wrapper/fortran/external_routines/test_external_procedures.py::test_namespace_imported_module_rejects_external_marker_before_codegen` | non-generating: validation/failure-path assertion | external symbols/native linkage | `not-applicable` |
 | `tests/wrapper/fortran/external_routines/test_external_procedures.py::test_one_source_with_several_standalone_externals_exports_each_at_root[*]` | source/generated-.pyi parity or parametrized route | scalar external symbols; explicit bridge interfaces | `wrapper-plan` |

tests/runtime/handles/test_array_actual_abi.py

@@ -467,6 +467,67 @@ def test_array_actual_argument_abi_packer_flattens_leading_edge_before_checked_s
     ) == (values.ctypes.data, 6, 4)
 
 
+@pytest.mark.parametrize(
+    ("values", "expected_rank", "expected_shape", "flat_axis", "message"),
+    [
+        (
+            np.array(1.0, dtype=np.float64),
+            1,
+            (None,),
+            0,
+            "expects NumPy array rank 1 through 15",
+        ),
+        (
+            np.ones((2,), dtype=np.float64),
+            2,
+            (2, None),
+            1,
+            "expects NumPy array rank at least 2",
+        ),
+        (
+            np.ones((2, 3, 4), dtype=np.float64),
+            3,
+            (2, None, 4),
+            1,
+            "axis must be the first or final contract dimension",
+        ),
+        (
+            np.ones((2, 3, 4), dtype=np.float64),
+            2,
+            (3, None),
+            1,
+            "incompatible shape at axis 0",
+        ),
+        (
+            np.ones((2, 3, 4), dtype=np.float64),
+            2,
+            (None, 3),
+            0,
+            "incompatible shape at axis 2",
+        ),
+    ],
+)
+def test_array_actual_argument_abi_packer_rejects_invalid_flat_shapes(
+    values,
+    expected_rank,
+    expected_shape,
+    flat_axis,
+    message,
+):
+    with pytest.raises((TypeError, ValueError), match=message):
+        _native_array_actual_argument_for_binding_positional(
+            values,
+            expected_dtype=np.float64,
+            expected_rank=expected_rank,
+            expected_shape=expected_shape,
+            require_native_byte_order=True,
+            require_aligned=True,
+            require_contiguous=True,
+            flatten_storage=True,
+            flat_axis=flat_axis,
+        )
+
+
 def test_array_actual_argument_abi_packer_flattens_native_handle_shape():
     actual = _handoff(252)
     handle = AllocatableArray(

tests/runtime/test_contract_constructors.py

@@ -8,6 +8,7 @@
     AllocatableArray,
     PointerArray,
     _bind_contract_native_array_handle,
+    _native_array_actual_for_binding,
     _native_array_descriptor_argument_for_binding,
     _native_array_descriptor_handoff_for_binding,
 )
@@ -111,6 +112,7 @@ def source_nullify(_handle):
     assert target.associated is True
     assert target.shape == (3,)
     np.testing.assert_array_equal(target.to_numpy(), value)
+    assert _native_array_actual_for_binding(target).address == value.ctypes.data
 
     source.nullify()
     assert source.associated is False
@@ -232,6 +234,107 @@ def bind_default(value):
     assert calls == [("destroy", owner)]
 
 
+@pytest.mark.parametrize(
+    ("prepare", "descriptor_kind", "dtype", "rank", "error", "message"),
+    [
+        (
+            lambda: AllocatableArray(
+                dtype="float64",
+                rank=1,
+                ops={
+                    "shape": lambda _handle: None,
+                    "array_actual": lambda _handle: None,
+                    "descriptor": lambda _handle: None,
+                    "allocated": lambda _handle: False,
+                },
+                to_numpy_policy="unsupported",
+            ),
+            "allocatable",
+            "float64",
+            1,
+            TypeError,
+            "fresh contract handle",
+        ),
+        (
+            lambda: contracts.Allocatable[contracts.Float64[:]](),
+            "pointer",
+            "float64",
+            1,
+            TypeError,
+            "cannot attach pointer descriptor storage",
+        ),
+        (
+            lambda: contracts.Allocatable[contracts.Float64[:]](),
+            "allocatable",
+            "float64",
+            2,
+            ValueError,
+            "does not match generated rank 2",
+        ),
+        (
+            lambda: contracts.Allocatable[contracts.Float64[:]](),
+            "allocatable",
+            "int32",
+            1,
+            TypeError,
+            "does not match generated dtype",
+        ),
+    ],
+)
+def test_generated_storage_rejects_incompatible_contract_handles(
+    prepare,
+    descriptor_kind,
+    dtype,
+    rank,
+    error,
+    message,
+):
+    handle = prepare()
+
+    with pytest.raises(error, match=message):
+        _bind_contract_native_array_handle(
+            handle,
+            descriptor_kind,
+            dtype,
+            rank,
+            {},
+            object(),
+            "owned",
+            "unsupported",
+        )
+
+
+def test_generated_storage_rejects_a_closed_contract_handle():
+    handle = contracts.Allocatable[contracts.Float64[:]]()
+    handle.close()
+
+    with pytest.raises(ReferenceError, match="handle is closed"):
+        _bind_contract_native_array_handle(
+            handle,
+            "allocatable",
+            "float64",
+            1,
+            {},
+            object(),
+            "owned",
+            "unsupported",
+        )
+
+
+def test_pointer_association_rejects_closed_handles():
+    target = contracts.Pointer[contracts.Float64[:]]()
+    source = contracts.Pointer[contracts.Float64[:]]()
+    target.close()
+
+    with pytest.raises(ReferenceError, match="pointer handle is closed"):
+        target.associate(source)
+
+    target = contracts.Pointer[contracts.Float64[:]]()
+    source.close()
+    with pytest.raises(ReferenceError, match="source pointer handle is closed"):
+        target.associate(source)
+
+
 def test_non_array_descriptor_and_ordinary_array_annotations_are_not_factories():
     with pytest.raises(TypeError, match="scalar allocatable contracts"):
         contracts.Allocatable[contracts.Float64]()

tests/semantics/policy/test_wrapper_policy.py

@@ -906,6 +906,32 @@ def raw_labels(n: Int32, labels: Addr(String[8][n])) -> None: ...
     assert labels.array.itemsize == 8
 
 
+def test_scalar_storage_rejects_incompatible_explicit_ownership_metadata():
+    module = parse_pyi_text(
+        """
+def invalid(
+    value: Annotated[
+        Int32[()],
+        Ownership("python"),
+        Transfer("snapshot_copy"),
+        Destruction("python_refcount"),
+    ],
+) -> None: ...
+""",
+        module_name="invalid_scalar_storage_ownership",
+    )
+    complete_semantic_policies(module)
+    policy = module.functions[0].metadata[RESOLVED_FUNCTION_WRAPPER_POLICY_METADATA]
+
+    assert policy.supported is False
+    assert policy.blockers[:4] == (
+        "argument 'value' scalar-storage owner is python, not caller",
+        "argument 'value' scalar-storage transfer is snapshot_copy, not in_place",
+        "argument 'value' scalar-storage destruction is python_refcount, not caller",
+        "argument 'value' scalar-storage action is snapshot_copy, not a storage-address action",
+    )
+
+
 def test_wrapper_policy_keeps_optional_raw_array_addresses_blocked():
     module = parse_pyi_text(
         "def optional_raw(n: Int32, values: Addr(Float64[n]) = ...) -> None: ...",

tests/wrapper/CHECKLIST_COVERAGE.md

@@ -47,6 +47,7 @@ recorded progression, not in the live ledger.
 | External bridge placement and module-procedure contrast | `external_routines/test_external_procedures.py::test_classic_external_bridge_uses_implicit_declaration_and_no_module_use`, `external_routines/test_external_procedures.py::test_module_procedure_bridge_uses_native_module_scope` |
 | `@external` with `@bind` and handwritten source-free contracts | `external_routines/test_external_procedures.py::test_external_bind_renames_python_export_without_changing_native_call` |
 | C-order flat storage over assumed-size native external buffers | `external_routines/test_external_procedures.py::test_handwritten_c_order_flat_contract_passes_rank_preserving_bridge_view` |
+| Handwritten flat, scalar-storage, optional-presence, and allocatable external contracts compile and run through their completed plans | `external_routines/test_external_procedures.py::test_handwritten_fortran_order_flat_contract_flattens_the_final_python_axes`, `external_routines/test_external_procedures.py::test_optional_flat_contracts_preserve_present_and_absent_calls`, `external_routines/test_external_procedures.py::test_external_allocatable_argument_accepts_a_caller_created_handle` |
 | Invalid root/module placement edits fail before code generation | `external_routines/test_external_procedures.py::test_package_entry_rejects_non_external_root_declaration_before_codegen`, `external_routines/test_external_procedures.py::test_namespace_imported_module_rejects_external_marker_before_codegen` |
 
 ## Stage 5 — Full Generated-Contract Runtime Parity