structuremappingmemory 1.0.0__py3-none-any.whl

sma/ontology/graph.py

@@ -0,0 +1,58 @@
+"""Normalized ontology graph contract shared across the ontology package.
+
+The graph is a small, serializable representation of an OBO/OWL ontology: a
+flat map of term ids to :class:`Term` records, with helpers that yield the
+is-a and typed-relation edges actually used to build the predicate lattice and
+higher-order case statements. Obsolete terms (and any edge touching one) are
+skipped by the edge iterators.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Iterator
+
+
+@dataclass
+class Term:
+    """A single ontology term.
+
+    ``id`` is the canonical prefixed id (e.g. ``"HP:0001250"``); ``parents``
+    are is_a parent ids; ``relations`` are typed ``(rel_type, target_id)`` pairs
+    (e.g. ``("part_of", "GO:0005634")``).
+    """
+
+    id: str
+    name: str = ""
+    parents: tuple[str, ...] = ()
+    relations: tuple[tuple[str, str], ...] = ()
+    obsolete: bool = False
+
+
+@dataclass
+class OntologyGraph:
+    """A flat, normalized view of an ontology."""
+
+    name: str
+    version: str = ""
+    terms: dict[str, Term] = field(default_factory=dict)
+
+    def active_terms(self) -> dict[str, Term]:
+        """Return only the non-obsolete terms."""
+        return {tid: term for tid, term in self.terms.items() if not term.obsolete}
+
+    def is_a_edges(self) -> Iterator[tuple[str, str]]:
+        """Yield ``(child_id, parent_id)`` is_a edges with both endpoints active."""
+        active = self.active_terms()
+        for child_id, term in active.items():
+            for parent_id in term.parents:
+                if parent_id in active:
+                    yield child_id, parent_id
+
+    def typed_relations(self) -> Iterator[tuple[str, str, str]]:
+        """Yield ``(subj_id, rel_type, obj_id)`` typed relations, active only."""
+        active = self.active_terms()
+        for subj_id, term in active.items():
+            for rel_type, obj_id in term.relations:
+                if obj_id in active:
+                    yield subj_id, rel_type, obj_id

sma/ontology/loader.py

@@ -0,0 +1,262 @@
+"""Universal OBO/OWL ontology loaders into the normalized :class:`OntologyGraph`.
+
+``load_obo`` parses the OBO flat-file ``[Term]`` blocks; ``load_owl`` parses the
+common RDF/XML subset using the stdlib ``xml.etree`` only (rdflib is not a
+dependency). ``load_ontology`` dispatches on the file extension.
+"""
+
+from __future__ import annotations
+
+import xml.etree.ElementTree as ET
+from pathlib import Path
+
+from .graph import OntologyGraph, Term
+
+# Known prefixes whose underscore-encoded OWL ids should be restored to a colon
+# form (e.g. ``HP_0001250`` -> ``HP:0001250``).
+_KNOWN_PREFIXES = (
+    "HP", "GO", "MONDO", "MP", "CHEBI", "UBERON", "CL", "DOID", "SO", "PATO",
+    "NCBITaxon", "EFO", "ORDO", "OMIM", "TST",
+)
+
+
+def fid(term_id: str) -> str:
+    """Functor-safe id: ``HP:0001250`` -> ``HP_0001250``."""
+    return term_id.replace(":", "_")
+
+
+def load_ontology(path: str, name: str = "") -> OntologyGraph:
+    """Load an ontology, dispatching on the ``.obo``/``.owl``/``.owl.xml`` extension."""
+    lower = str(path).lower()
+    if lower.endswith(".obo"):
+        return load_obo(path, name=name)
+    if lower.endswith(".owl") or lower.endswith(".owl.xml") or lower.endswith(".rdf") or lower.endswith(".xml"):
+        return load_owl(path, name=name)
+    raise ValueError(f"Unrecognized ontology extension: {path}")
+
+
+# --------------------------------------------------------------------------- #
+# OBO
+# --------------------------------------------------------------------------- #
+def load_obo(path: str, name: str = "") -> OntologyGraph:
+    """Parse an OBO flat file into an :class:`OntologyGraph`."""
+    version = ""
+    header_ontology = ""
+    terms: dict[str, Term] = {}
+
+    in_term = False
+    cur_id = ""
+    cur_name = ""
+    cur_parents: list[str] = []
+    cur_relations: list[tuple[str, str]] = []
+    cur_obsolete = False
+
+    def flush() -> None:
+        nonlocal cur_id, cur_name, cur_parents, cur_relations, cur_obsolete
+        if cur_id and ":" in cur_id:
+            terms[cur_id] = Term(
+                id=cur_id,
+                name=cur_name,
+                parents=tuple(cur_parents),
+                relations=tuple(cur_relations),
+                obsolete=cur_obsolete,
+            )
+        cur_id = ""
+        cur_name = ""
+        cur_parents = []
+        cur_relations = []
+        cur_obsolete = False
+
+    with open(path, "r", encoding="utf-8") as handle:
+        for raw in handle:
+            line = raw.rstrip("\n")
+            stripped = line.strip()
+            if stripped.startswith("[") and stripped.endswith("]"):
+                # New stanza. Flush any pending term, then track whether we are
+                # entering a [Term] stanza (others, like [Typedef], are ignored).
+                if in_term:
+                    flush()
+                in_term = stripped == "[Term]"
+                continue
+
+            if not in_term:
+                # Header region (before any stanza).
+                if stripped.startswith("data-version:"):
+                    version = stripped[len("data-version:"):].strip()
+                elif stripped.startswith("ontology:") and not header_ontology:
+                    header_ontology = stripped[len("ontology:"):].strip()
+                continue
+
+            if stripped.startswith("id:"):
+                cur_id = stripped[len("id:"):].strip()
+            elif stripped.startswith("name:"):
+                cur_name = stripped[len("name:"):].strip()
+            elif stripped.startswith("is_a:"):
+                token = stripped[len("is_a:"):].strip().split("!", 1)[0].strip()
+                token = token.split()[0] if token else ""
+                if ":" in token:
+                    cur_parents.append(token)
+            elif stripped.startswith("relationship:"):
+                rest = stripped[len("relationship:"):].strip().split("!", 1)[0].strip()
+                parts = rest.split()
+                if len(parts) >= 2 and ":" in parts[1]:
+                    cur_relations.append((parts[0], parts[1]))
+            elif stripped.startswith("is_obsolete:"):
+                if stripped[len("is_obsolete:"):].strip().lower() == "true":
+                    cur_obsolete = True
+
+    if in_term:
+        flush()
+
+    if not name:
+        name = header_ontology or Path(path).stem
+    name = name.removesuffix(".obo")
+    return OntologyGraph(name=name, version=version, terms=terms)
+
+
+# --------------------------------------------------------------------------- #
+# OWL / RDF-XML
+# --------------------------------------------------------------------------- #
+def _local(tag: str) -> str:
+    """Strip the namespace from an etree tag: ``{uri}label`` -> ``label``."""
+    return tag.rsplit("}", 1)[-1] if "}" in tag else tag
+
+
+def _attr(elem: ET.Element, local_name: str) -> str | None:
+    """Fetch an attribute by local name, ignoring namespace prefix."""
+    for key, value in elem.attrib.items():
+        if _local(key) == local_name:
+            return value
+    return None
+
+
+def _term_id_from_iri(iri: str) -> str:
+    """Derive a compact prefixed term id from an IRI.
+
+    Takes the fragment after ``#`` or the final ``/`` and restores the colon for
+    known prefixes (``HP_0001250`` -> ``HP:0001250``).
+    """
+    frag = iri.rsplit("#", 1)[-1]
+    frag = frag.rsplit("/", 1)[-1]
+    if "_" in frag:
+        prefix, _, rest = frag.partition("_")
+        if prefix in _KNOWN_PREFIXES and rest:
+            return f"{prefix}:{rest}"
+    return frag
+
+
+def load_owl(path: str, name: str = "") -> OntologyGraph:
+    """Parse the common RDF/XML subset of an OWL ontology (stdlib etree only)."""
+    tree = ET.parse(path)
+    root = tree.getroot()
+
+    version = ""
+    terms: dict[str, Term] = {}
+
+    for elem in root.iter():
+        local = _local(elem.tag)
+
+        if local == "Ontology":
+            for child in list(elem):
+                clocal = _local(child.tag)
+                if clocal == "versionIRI":
+                    res = _attr(child, "resource")
+                    if res:
+                        version = version or res
+                elif clocal == "versionInfo":
+                    if child.text and child.text.strip():
+                        version = version or child.text.strip()
+            continue
+
+        if local != "Class":
+            continue
+
+        about = _attr(elem, "about") or _attr(elem, "ID")
+        if not about:
+            continue
+        term_id = _term_id_from_iri(about)
+
+        term_name = ""
+        parents: list[str] = []
+        relations: list[tuple[str, str]] = []
+        obsolete = False
+
+        for child in list(elem):
+            clocal = _local(child.tag)
+            if clocal == "label":
+                if child.text and not term_name:
+                    term_name = child.text.strip()
+            elif clocal == "deprecated":
+                if child.text and child.text.strip().lower() == "true":
+                    obsolete = True
+            elif clocal == "subClassOf":
+                resource = _attr(child, "resource")
+                if resource:
+                    parents.append(_term_id_from_iri(resource))
+                    continue
+                # Anonymous superclass: look for an owl:Restriction.
+                for restr in child.iter():
+                    if _local(restr.tag) != "Restriction":
+                        continue
+                    rel_type = ""
+                    target = ""
+                    for rchild in list(restr):
+                        rlocal = _local(rchild.tag)
+                        if rlocal == "onProperty":
+                            res = _attr(rchild, "resource")
+                            if res:
+                                rel_type = _local(_term_id_from_iri(res))
+                        elif rlocal == "someValuesFrom":
+                            res = _attr(rchild, "resource")
+                            if res:
+                                target = _term_id_from_iri(res)
+                    if rel_type and target:
+                        relations.append((rel_type, target))
+
+        terms[term_id] = Term(
+            id=term_id,
+            name=term_name,
+            parents=tuple(parents),
+            relations=tuple(relations),
+            obsolete=obsolete,
+        )
+
+    if not name:
+        name = Path(path).stem
+    name = name.removesuffix(".owl")
+    return OntologyGraph(name=name, version=version, terms=terms)
+
+
+def load_owl_dir(root: str, name: str = "", pattern: str = "*.rdf") -> OntologyGraph:
+    """Load + merge a multi-file OWL/RDF ontology (e.g. LKIF, FIBO) into one graph.
+
+    Many real OWL ontologies ship as a directory of modules rather than a single
+    file. This loads every file matching ``pattern`` under ``root`` (recursively)
+    and merges their terms. On id collision the first non-empty term wins; a later
+    file may fill in a missing label or add parents/relations.
+    """
+    root_path = Path(root)
+    files = sorted(root_path.rglob(pattern)) if root_path.is_dir() else [root_path]
+    merged: dict[str, Term] = {}
+    version = ""
+    for f in files:
+        try:
+            g = load_owl(str(f), name=name)
+        except ET.ParseError:
+            continue  # skip non-RDF/XML or malformed module files
+        version = version or g.version
+        for tid, term in g.terms.items():
+            cur = merged.get(tid)
+            if cur is None:
+                merged[tid] = term
+                continue
+            merged[tid] = Term(
+                id=tid,
+                name=cur.name or term.name,
+                parents=tuple(dict.fromkeys((*cur.parents, *term.parents))),
+                relations=tuple(dict.fromkeys((*cur.relations, *term.relations))),
+                obsolete=cur.obsolete and term.obsolete,
+            )
+    if not name:
+        name = root_path.stem
+    return OntologyGraph(name=name, version=version, terms=merged)

sma/ontology/mitre_xml.py

@@ -0,0 +1,67 @@
+"""Loaders for MITRE CAPEC (attack patterns) and CWE (software weaknesses) XML.
+
+Both ship as a flat list of entries with explicit ``ChildOf`` relations that form
+a deep is-a hierarchy, plus other typed relations (CanPrecede/CanFollow/PeerOf,
+and CAPEC->CWE ``exploits`` links). These enrich the cyber domain beyond ATT&CK's
+shallow tactic/technique tree with real subsumption depth and cross-links.
+"""
+from __future__ import annotations
+
+import xml.etree.ElementTree as ET
+
+from .graph import OntologyGraph, Term
+
+_KINDS = {
+    # kind: (entry_tag, id_prefix, related_tag, id_attr)
+    "capec": ("Attack_Pattern", "CAPEC", "Related_Attack_Pattern", "CAPEC_ID"),
+    "cwe": ("Weakness", "CWE", "Related_Weakness", "CWE_ID"),
+}
+
+
+def _local(tag: str) -> str:
+    return tag.rsplit("}", 1)[-1] if "}" in tag else tag
+
+
+def load_mitre_xml(path: str, kind: str, name: str = "") -> OntologyGraph:
+    entry_tag, prefix, related_tag, id_attr = _KINDS[kind]
+    name = name or kind
+    tree = ET.parse(path)
+    terms: dict[str, Term] = {}
+    version = tree.getroot().get("Version", "")
+    for elem in tree.getroot().iter():
+        if _local(elem.tag) != entry_tag:
+            continue
+        eid = elem.get("ID")
+        if not eid:
+            continue
+        tid = f"{prefix}-{eid}"
+        obsolete = (elem.get("Status", "") or "").lower() in ("deprecated", "obsolete")
+        parents: list[str] = []
+        relations: list[tuple[str, str]] = []
+        for rel in elem.iter():
+            rlocal = _local(rel.tag)
+            if rlocal == related_tag:
+                nature = rel.get("Nature", "")
+                target = rel.get(id_attr)
+                if not target:
+                    continue
+                if nature == "ChildOf":
+                    parents.append(f"{prefix}-{target}")
+                elif nature:
+                    relations.append((nature, f"{prefix}-{target}"))
+            elif rlocal == "Related_Weakness" and kind == "capec":
+                cwe = rel.get("CWE_ID")
+                if cwe:
+                    relations.append(("exploits", f"CWE-{cwe}"))
+        terms[tid] = Term(id=tid, name=elem.get("Name", ""),
+                          parents=tuple(dict.fromkeys(parents)),
+                          relations=tuple(dict.fromkeys(relations)), obsolete=obsolete)
+    return OntologyGraph(name=name, version=version, terms=terms)
+
+
+def load_capec(path: str, name: str = "capec") -> OntologyGraph:
+    return load_mitre_xml(path, "capec", name=name)
+
+
+def load_cwe(path: str, name: str = "cwe") -> OntologyGraph:
+    return load_mitre_xml(path, "cwe", name=name)

sma/ontology/mount.py

@@ -0,0 +1,101 @@
+"""Mount a normalized :class:`OntologyGraph` onto SMA's matching machinery.
+
+Mounting lifts an ontology's is_a hierarchy into a :class:`Canonicalizer`
+predicate lattice (so structurally-distinct-but-related terms can ascend to a
+shared ancestor during matching) and provides the case/index builders that turn
+a set of present terms into an SMA :class:`Case`.
+
+A term ``T`` present on a subject becomes the statement ``fid(T)(subject)``;
+each typed relation ``(s, rel, o)`` whose *both* endpoints are present becomes
+the higher-order statement ``rel(fid(s)(subject), fid(o)(subject))``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Iterable, Mapping
+
+from sma.index.macfac import MacFacIndex
+from sma.ir.canon import Canonicalizer
+from sma.ir.schema import Case, entity, make_case, stmt
+from sma.match.types import MatchConfig
+
+from .graph import OntologyGraph
+from .loader import fid
+
+
+def _default_config() -> MatchConfig:
+    """Ontology matching default: ascend up to two is_a hops (``delta=2``)."""
+    return MatchConfig(delta=2, rho=0.95)
+
+
+@dataclass
+class MountedOntology:
+    """An :class:`OntologyGraph` bound to a populated :class:`Canonicalizer`."""
+
+    graph: OntologyGraph
+    canon: Canonicalizer
+    config: MatchConfig
+
+    def build_case(
+        self,
+        term_ids: Iterable[str],
+        subject: str = "subject",
+        metadata: Mapping[str, Any] | None = None,
+    ) -> Case:
+        """Build a :class:`Case` for the given present ``term_ids``.
+
+        Unknown term ids (not in ``graph.terms``) are dropped. Each present term
+        contributes ``fid(term)(subject)``; each typed relation with both
+        endpoints present contributes the higher-order
+        ``rel(fid(s)(subject), fid(o)(subject))``.
+        """
+        present = [t for t in term_ids if t in self.graph.terms]
+        present_set = set(present)
+        subj = entity(subject, subject)
+
+        statements = [stmt(fid(t), subj) for t in present]
+        for s, rel, o in self.graph.typed_relations():
+            if s in present_set and o in present_set:
+                statements.append(stmt(rel, stmt(fid(s), subj), stmt(fid(o), subj)))
+
+        return make_case(statements, metadata=metadata)
+
+    def build_index(
+        self,
+        records: Iterable[tuple[str, Iterable[str], Mapping[str, Any] | None]],
+        config: MatchConfig | None = None,
+    ) -> MacFacIndex:
+        """Build a :class:`MacFacIndex` over ``(key, term_ids, metadata)`` records.
+
+        Each record's ``key`` is stored under ``metadata["key"]`` and the
+        returned index carries a ``key_of`` attribute mapping ``case_id -> key``
+        so callers can recover the original key from a retrieval result.
+        """
+        cases: list[Case] = []
+        key_of: dict[str, str] = {}
+        for key, term_ids, metadata in records:
+            md = dict(metadata or {})
+            md["key"] = key
+            case = self.build_case(term_ids, metadata=md)
+            cases.append(case)
+            key_of[case.case_id] = key
+
+        index = MacFacIndex(config=config or self.config, canon=self.canon)
+        index.build(cases)
+        index.key_of = key_of
+        return index
+
+
+def mount(graph: OntologyGraph, config: MatchConfig | None = None) -> MountedOntology:
+    """Mount ``graph``: populate a predicate lattice from its is_a edges.
+
+    Every ``(child, parent)`` in :meth:`OntologyGraph.is_a_edges` becomes a
+    lattice edge ``fid(child) -> fid(parent)``. The default config ascends up to
+    two hops (``MatchConfig(delta=2, rho=0.95)``).
+    """
+    cfg = config or _default_config()
+    canon = Canonicalizer()
+    for child, parent in graph.is_a_edges():
+        canon.lattice.add(fid(child), fid(parent))
+    return MountedOntology(graph=graph, canon=canon, config=cfg)

sma/ontology/rdf_loader.py

@@ -0,0 +1,75 @@
+"""Complete RDF loader using rdflib (for ontologies our xml.etree subset misses).
+
+Unlike :func:`sma.ontology.loader.load_owl` (a stdlib RDF/XML subset), this uses
+rdflib to fully parse OWL — including Turtle, restrictions, and the complete class
+graph — for ontologies like FIBO whose power lives in typed relations expressed
+via ``owl:Restriction``. Falls back gracefully if rdflib is absent.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+from .graph import OntologyGraph, Term
+from .loader import _KNOWN_PREFIXES
+
+
+def _compact(uri: str) -> str:
+    frag = str(uri).rsplit("#", 1)[-1].rsplit("/", 1)[-1]
+    if "_" in frag:
+        prefix, _, rest = frag.partition("_")
+        if prefix in _KNOWN_PREFIXES and rest:
+            return f"{prefix}:{rest}"
+    return frag
+
+
+def load_rdflib(path: str, name: str = "", fmt: str | None = None,
+                pattern: str = "*.rdf") -> OntologyGraph:
+    """Load an OWL/RDF ontology (file, Turtle, or a directory of RDF files) via rdflib."""
+    import logging
+    import rdflib
+    from rdflib import OWL, RDF, RDFS
+    from rdflib.namespace import DC, DCTERMS
+
+    # FIBO metadata carries malformed xsd:dateTime literals; rdflib logs a
+    # traceback per occurrence but parses fine. Silence that noise.
+    logging.getLogger("rdflib.term").setLevel(logging.CRITICAL)
+
+    g = rdflib.Graph()
+    root = Path(path)
+    files = sorted(root.rglob(pattern)) if root.is_dir() else [root]
+    for f in files:
+        try:
+            g.parse(str(f), format=fmt) if fmt else g.parse(str(f))
+        except Exception:
+            continue
+
+    # Collect named owl:Class (and rdfs:Class) subjects with a real IRI.
+    terms: dict[str, Term] = {}
+    classes = set(g.subjects(RDF.type, OWL.Class)) | set(g.subjects(RDF.type, RDFS.Class))
+    for cls in classes:
+        if isinstance(cls, rdflib.BNode):
+            continue
+        tid = _compact(cls)
+        label = g.value(cls, RDFS.label) or g.value(cls, DCTERMS.title) or g.value(cls, DC.title)
+        parents: list[str] = []
+        relations: list[tuple[str, str]] = []
+        for sup in g.objects(cls, RDFS.subClassOf):
+            if isinstance(sup, rdflib.BNode):
+                # owl:Restriction -> typed relation (onProperty + someValuesFrom).
+                prop = g.value(sup, OWL.onProperty)
+                tgt = g.value(sup, OWL.someValuesFrom) or g.value(sup, OWL.allValuesFrom)
+                if prop is not None and tgt is not None and not isinstance(tgt, rdflib.BNode):
+                    relations.append((_compact(prop), _compact(tgt)))
+            else:
+                parents.append(_compact(sup))
+        obsolete = bool(g.value(cls, OWL.deprecated))
+        terms[tid] = Term(id=tid, name=str(label) if label else "",
+                          parents=tuple(dict.fromkeys(parents)),
+                          relations=tuple(dict.fromkeys(relations)), obsolete=obsolete)
+
+    version = ""
+    for o in g.objects(None, OWL.versionIRI):
+        version = str(o); break
+    if not name:
+        name = root.stem
+    return OntologyGraph(name=name, version=version, terms=terms)

sma/ontology/registry.py

@@ -0,0 +1,115 @@
+"""A small registry of named ontologies that loads and mounts them on demand.
+
+Each :class:`OntologyEntry` records where an ontology lives on disk and how to
+parse it; :meth:`OntologyRegistry.get` lazily loads the file into an
+:class:`~sma.ontology.graph.OntologyGraph`, mounts it (building the predicate
+lattice + match index machinery), and caches the result so repeated lookups are
+cheap.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from .loader import load_ontology
+
+if TYPE_CHECKING:  # pragma: no cover - typing only
+    from .mount import MountedOntology
+    from sma.match.types import MatchConfig
+
+
+def _infer_format(path: str) -> str:
+    """Infer the on-disk format from a path's extension.
+
+    ``.obo`` -> ``"obo"``; ``.owl``/``.owl.xml``/``.rdf``/``.xml`` -> ``"owl"``.
+    """
+    lower = str(path).lower()
+    if lower.endswith(".obo"):
+        return "obo"
+    if (
+        lower.endswith(".owl")
+        or lower.endswith(".owl.xml")
+        or lower.endswith(".rdf")
+        or lower.endswith(".xml")
+    ):
+        return "owl"
+    raise ValueError(f"Cannot infer ontology format from extension: {path}")
+
+
+@dataclass
+class OntologyEntry:
+    """A registered ontology: its name, source path, format, and version."""
+
+    name: str
+    path: str
+    format: str
+    version: str = ""
+
+
+class OntologyRegistry:
+    """A name-keyed collection of ontologies, loaded and mounted on demand."""
+
+    def __init__(self) -> None:
+        self._entries: dict[str, OntologyEntry] = {}
+        self._order: list[str] = []
+        self._mounted: dict[str, "MountedOntology"] = {}
+
+    def register(
+        self,
+        name: str,
+        path: str,
+        fmt: str | None = None,
+        version: str | None = None,
+    ) -> OntologyEntry:
+        """Register an ontology under ``name``.
+
+        ``fmt`` is inferred from the file extension when omitted. Re-registering
+        a name replaces its entry and invalidates any cached mounted ontology.
+        """
+        resolved_fmt = fmt if fmt is not None else _infer_format(path)
+        entry = OntologyEntry(
+            name=name,
+            path=str(path),
+            format=resolved_fmt,
+            version=version or "",
+        )
+        if name not in self._entries:
+            self._order.append(name)
+        self._entries[name] = entry
+        self._mounted.pop(name, None)
+        return entry
+
+    def get(self, name: str, config: "MatchConfig | None" = None) -> "MountedOntology":
+        """Load + mount the named ontology, caching the result.
+
+        The mounted ontology is cached on first access; subsequent calls return
+        the same object (identity-stable) without re-reading the file.
+        """
+        cached = self._mounted.get(name)
+        if cached is not None:
+            return cached
+
+        try:
+            entry = self._entries[name]
+        except KeyError:
+            raise KeyError(f"No ontology registered under {name!r}") from None
+
+        # Import lazily: mount.py is owned by a sibling agent and may bring in
+        # heavier match machinery; keep registry import-time light and decoupled.
+        from .mount import mount
+
+        graph = load_ontology(entry.path, name=entry.name)
+        if not entry.version and graph.version:
+            entry.version = graph.version
+        mounted = mount(graph, config=config)
+        self._mounted[name] = mounted
+        return mounted
+
+    def list(self) -> list[OntologyEntry]:
+        """Return registered entries in registration order."""
+        return [self._entries[name] for name in self._order]
+
+    def __contains__(self, name: object) -> bool:
+        return name in self._entries