Merge branch 'gtf-manifest' into gtf-buildingmotif (#30)

Manifests become a set of libraries stored as owl:imports. Merged clean:
nothing else on this branch touches the manifest API.

Author: gtfierro

.agents/skills/buildingmotif/references/validation.md

@@ -391,8 +391,9 @@ Two things in this script that trip people up:
 - **Passing shape collections replaces the manifest.** `model.validate([sc1, sc2])`
   validates against *only* `sc1, sc2` — the model's standing manifest is **not** added.
   That's usually what you want for an ad-hoc "does it support *this* app?" check. To
-  validate against the manifest plus extras, include `model.get_manifest()` in the list.
-  `model.validate()` with no list validates against the manifest alone.
+  validate against the manifest plus extras, spread `model.manifest.shape_collections()`
+  into the list. `model.validate()` with no list validates against the manifest alone —
+  that is, against the shape collections of every library the manifest names.
 - **`error_on_missing_imports=False` is the notebooks' default for real models.** A real
   model's shapes usually `owl:imports` something you haven't loaded; with `True` (the
   default) validation raises and stops. `False` gets you a report now — but always check

.agents/skills/buildingmotif/references/writing_shapes.md

@@ -26,8 +26,9 @@ these), and the shape you write depends on which:
    don't write these; you load them and validate against them to check the model *uses*
    the ontology correctly. `model.validate([brick.get_shape_collection()])`.
 2. **Manifest shapes** — your model's *standing* requirements: "this site has exactly 1
-   AHU, 1 supply fan, …". A manifest is a shape collection you associate with the model
-   via `model.add_to_manifest(...)`. Written with the `constraint:` vocabulary (below).
+   AHU, 1 supply fan, …". You write them into a library and add that library to the
+   model's manifest with `model.manifest.add(lib)`; the manifest is the set of libraries
+   the model claims to satisfy. Written with the `constraint:` vocabulary (below).
 3. **Application / use-case shapes** — "to run G36 §4.8, an AHU must have these points."
    These are the pointlist/equipment shapes that answer "is my model sufficient for X?"
    and are what most of this file is about. Libraries tag them as
@@ -214,17 +215,31 @@ associate it:
 
 ```python
 manifest = Library.from_ontology("my_manifest.ttl")
-model.add_to_manifest(manifest.get_shape_collection())
+model.manifest.add(manifest)
 ctx = model.validate()   # validates against the manifest by default
 ```
 
-`add_to_manifest` **merges** into whatever the model already has — call it twice and you get
-the union, so a manifest can grow but never shrink. To swap the requirements out wholesale,
-use `model.replace_manifest(sc)`, which discards the previous contents. Reach for `replace_`
-when re-running a script that would otherwise accumulate stale requirements across runs.
+The manifest is a **set of libraries**, so it behaves like one:
 
-(`update_manifest` is the old name for `add_to_manifest`. It still works and warns; the name
-was misleading, since it never replaced anything.)
+```python
+model.manifest.add(manifest, g36)        # Libraries, names, or iterables of either
+model.manifest.remove(g36)               # KeyError if absent; .discard() forgives
+model.manifest.library_names             # ['urn:my/manifest', ...]
+"urn:my/manifest" in model.manifest
+model.manifest.replace([manifest])       # the whole set at once
+model.manifest.libraries                 # the Library objects
+```
+
+Shapes only ever reach a manifest *through a library* — there is no way to append loose
+shapes to it. That is what makes the set inspectable and subtractable: a manifest that
+had absorbed a copy of some shapes could grow but never shrink, and could not say where
+anything came from. A name that is not a loaded library is resolved through the ontology
+environment (cache first, then a fetch if it is a URL), so
+`model.manifest.add("https://brickschema.org/schema/1.4/Brick")` loads Brick if it has
+to; a name that resolves nowhere raises rather than failing later at validation time.
+
+Storage-wise the manifest is a graph of `owl:imports` and nothing else —
+`model.manifest.graph` hands you a copy to serialize or diff.
 
 ### ⚠ `constraint:` components validate but block repair
 

API-CLEANUP.md

@@ -500,6 +500,15 @@ the old name implied), the latter built on `ShapeCollection.replace_graph`, so i
 copy-on-write -- a failure leaves the previous contents intact. `update_manifest` still works
 and warns. All 7 call sites migrated.
 
+**Superseded by the manifest rework (`gtf-manifest`).** This fix kept the manifest a *shape
+graph* and only made its two mutations honest, which left the underlying problem: a manifest
+made of copied triples has nothing to subtract by name, cannot say where a shape came from,
+and goes stale when its source library is reloaded. A manifest is now a **set of libraries**
+stored as `owl:imports` -- `model.manifest.add(lib)` / `.remove(lib)` -- so `add_to_manifest`
+takes libraries rather than shape collections, `replace_manifest` becomes
+`model.manifest.replace([...])`, and `update_manifest` is gone rather than deprecated. See
+`docs/explanations/manifests.md`.
+
 ---
 
 ## Proposed, not yet done

buildingmotif/api/views/model.py

@@ -177,7 +177,10 @@ def validate_model(models_id: int) -> flask.Response:
 
     # no body provided -- default to model manifest
     if request.content_length is None:
-        shape_collections = [model.get_manifest()]
+        # error_on_missing=False for the same reason validate() below passes
+        # error_on_missing_imports=False: a service should report what it could
+        # check rather than 500 because one manifest entry is unloadable.
+        shape_collections = model.manifest.shape_collections(error_on_missing=False)
     else:
         # get body
         if request.content_type != "application/json":

buildingmotif/dataclasses/__init__.py

@@ -5,6 +5,7 @@
     RepairWitness,
 )
 from buildingmotif.dataclasses.library import Library  # noqa
+from buildingmotif.dataclasses.manifest import Manifest, ManifestLibraryNotFound  # noqa
 from buildingmotif.dataclasses.model import Model  # noqa
 from buildingmotif.dataclasses.shape_collection import ShapeCollection  # noqa
 from buildingmotif.dataclasses.template import IncompleteTemplateError, Template  # noqa