docs: say what compile() does, not what add() did

The note left by the expansion commit read "compile() runs inference
against everything the members import", which puts the emphasis in the
wrong place and invites the reading that compile resolves imports. It
does not: it unions exactly the shape collections of the listed members
and resolves nothing. Verified -- the number of shape collections equals
the number of members, for import_depth=-1 and =0 alike.

A dependency is compiled against only when it is itself a member, which
add() arranges by expanding imports; add(..., import_depth=0) leaves them
genuinely absent. Comment, explanation page, wording only.

Author: gtfierro

buildingmotif/dataclasses/model.py

@@ -330,10 +330,11 @@ def compile(
             manifest = self.manifest
             shape_collections = manifest.shape_collections()
         backend = get_shacl_backend(shacl_engine or self._bm.shacl_engine)
-        # Compiling against the members is compiling against everything they
-        # import, because a manifest expands imports when a library is added
-        # rather than resolving them here. There is deliberately no separate
-        # resolution step: the explicit membership is the whole story.
+        # Exactly the shape collections listed: no import resolution happens
+        # here, and none is wanted. A dependency is compiled against only if
+        # it is itself a member, which add() arranges by expanding imports at
+        # the time a library is added (add(..., import_depth=0) opts out, and
+        # then its imports are genuinely absent here).
         compiled_graph = backend.compile_model_graph(self.graph, shape_collections)
         return CompiledModel(
             self,

docs/explanations/manifests.md

@@ -123,9 +123,13 @@ since it was added, or one added with `import_depth=0`. It raises
 
 `model.manifest.shape_collections()` is the list `validate()` and `compile()` use: the
 shape collection of each member library, in name order. The manifest's own graph is *not*
-in that list — it holds imports, not shapes. Since the membership is complete, `compile()`
-runs inference against everything the members import as well; there is deliberately no
-separate resolution step for it to skip.
+in that list — it holds imports, not shapes.
+
+Both work on **exactly** those members. Neither resolves imports: a dependency is validated
+and compiled against only if it is itself a member, which `add` arranges. Add a library
+with `import_depth=0` and its imports are genuinely absent from both — that is the
+difference between "the manifest lists it" and "something will find it later", and the
+manifest only ever means the first.
 
 Passing shape collections explicitly still bypasses the manifest entirely:
 `model.validate([sc1, sc2])` checks against exactly those. To validate against the