sunstone-data-platform 1.4.0__tar.gz → 1.5.0__tar.gz

{sunstone_data_platform-1.4.0 → sunstone_data_platform-1.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sunstone-data-platform
-Version: 1.4.0
+Version: 1.5.0
 Summary: Sunstone Data Platform - Data lakehouse with semantic metadata
 Author-email: Sunstone Institute <stig@sunstone.institute>
 License-Expression: MIT

{sunstone_data_platform-1.4.0 → sunstone_data_platform-1.5.0}/src/sunstone_data/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.4.0'
-__version_tuple__ = version_tuple = (1, 4, 0)
+__version__ = version = '1.5.0'
+__version_tuple__ = version_tuple = (1, 5, 0)
 
 __commit_id__ = commit_id = None

{sunstone_data_platform-1.4.0 → sunstone_data_platform-1.5.0}/src/sunstone_data/cli/commands/conceptmap.py

@@ -9,6 +9,7 @@ from pathlib import Path
 
 import typer
 
+from sunstone_data.branch import current_data_branch
 from sunstone_data.cli._app import console, data_app
 from sunstone_data.cli._errors import cli_errors
 
@@ -16,11 +17,18 @@ conceptmap_app = typer.Typer(help="Push concept maps from map-concepts scope dir
 data_app.add_typer(conceptmap_app, name="conceptmap")
 
 _SCOPE_DIR = typer.Argument(
-    ..., help="Scope directory written by map-concepts (reads scheme/*.ttl and scheme/mappings.sssom.tsv)"
+    ...,
+    help=(
+        "Scope directory written by /kg:map-concepts. Reads scheme/*.ttl (IRIs relative to the concept map) and "
+        "scheme/mappings.sssom.tsv, and uploads the files named by cmap:contentPath as private blobs"
+    ),
+)
+_BRANCH = typer.Option(
+    None,
+    "--branch",
+    "-b",
+    help="Data branch to write, never main (default: the normalized git branch, else the CI ref; fails if neither)",
 )
-# Concept maps are published content, so the default is main, not the git
-# branch of the directory the command runs in (DP-REQ-30).
-_BRANCH = typer.Option("main", "--branch", "-b", help="Branch to write")
 _BRANCH_READ = typer.Option("main", "--branch", "-b", help="Branch to read")
 _JSON = typer.Option(False, "--json", help="Output as JSON")
 
@@ -42,26 +50,34 @@ def _report(result, json_output: bool) -> None:
 
 
 @conceptmap_app.command("create")
-def create_cmd(scope_dir: Path = _SCOPE_DIR, branch: str = _BRANCH, json_output: bool = _JSON) -> None:
-    """Allocate a new concept map and push the scope directory to it."""
+def create_cmd(scope_dir: Path = _SCOPE_DIR, branch: str | None = _BRANCH, json_output: bool = _JSON) -> None:
+    """Allocate a new concept map and push the scope directory to it.
+
+    Writes to a data branch, never main; merge it with `sunstone data branch merge <branch>`.
+    Source content files go to the catalog namespace shared/conceptmap_<n> as non-public blobs,
+    linked from their source with cmap:contentBlob.
+    """
     with cli_errors(json_output):
         from sunstone_data import conceptmap
 
-        _report(conceptmap.create(scope_dir, branch), json_output)
+        _report(conceptmap.create(scope_dir, branch or current_data_branch()), json_output)
 
 
 @conceptmap_app.command("update")
 def update_cmd(
     n: int = typer.Argument(..., help="Concept map id, the <n> in /conceptmap/<n>"),
     scope_dir: Path = _SCOPE_DIR,
-    branch: str = _BRANCH,
+    branch: str | None = _BRANCH,
     json_output: bool = _JSON,
 ) -> None:
-    """Replace an existing concept map with the scope directory."""
+    """Replace an existing concept map with the scope directory, on a data branch (never main).
+
+    A missing branch is forked from main. Unchanged content files are not uploaded again.
+    """
     with cli_errors(json_output):
         from sunstone_data import conceptmap
 
-        _report(conceptmap.update(n, scope_dir, branch), json_output)
+        _report(conceptmap.update(n, scope_dir, branch or current_data_branch()), json_output)
 
 
 @conceptmap_app.command("sssom")

sunstone_data_platform-1.5.0/src/sunstone_data/conceptmap.py

@@ -0,0 +1,365 @@
+"""Publish a map-concepts scope directory as a concept map (DP-REQ-323).
+
+A scope directory written by `/kg:map-concepts` holds the concept map in
+`scheme/*.ttl` (including the research record, `scheme/research.ttl`). The
+platform mints the IRIs: each file uses relative IRIs and is parsed with base
+`{graph_iri}/`, and `{graph_iri}/` itself (written `<>`) becomes the graph IRI,
+which is also the concept scheme. So `<slug>` is a concept, `<ontology#Term>` an
+ontology term, `<cq/…>`, `<prompt/…>` and `<source/…>` the research record. A
+file may not declare its own base. Absolute IRIs under the local placeholder
+`https://data.sunstone.institute/conceptmap/0` (used by tools before a push, and
+in `mappings.sssom.tsv`) are moved onto the graph IRI too. Older scope dirs with
+absolute `https://sunstone.institute/rdf/scope/<N>/concept…` / `…/ontology…`
+IRIs still push: `…/concept` becomes the graph IRI and `…/ontology`
+`{graph_iri}/ontology`. Local files are never changed, so the same directory
+can be pushed again with `update`.
+
+Each `cmap:Source` whose `cmap:contentPath` names a file in the scope dir has
+that file uploaded as a non-public blob dataset in the catalog namespace
+`shared/conceptmap_<n>` (see `content_namespace`), and gets `cmap:contentBlob
+<dataset IRI>` before the graph is written. An unchanged file set is not
+uploaded again.
+
+`create` and `update` refuse `main`: the graph and the blobs go to a data
+branch, which `sunstone data branch merge` copies into main. Only the number
+allocation (`POST /conceptmaps/`) is global; it has no branch.
+
+- `create` allocates a new concept map (`POST /conceptmaps/`) and PUTs the
+  merged files to its named graph.
+- `update` replaces an existing concept map's named graph.
+- `sssom` writes a concept map's mappings back out as an SSSOM file.
+
+When the directory has `scheme/mappings.sssom.tsv`, its per-mapping metadata
+is pushed with the Turtle (see `sunstone_data.sssom`).
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING
+from urllib.parse import urlsplit
+
+from sunstone_data.config import get_settings
+from sunstone_data.graph.client import N_TRIPLES, ConflictError, GraphClient, NotFound, get_graph_client
+
+if TYPE_CHECKING:
+    from rdflib import Graph
+
+_SCOPE = re.compile(r"^https://sunstone\.institute/rdf/scope/\d+/(concept|ontology)(.*)$", re.DOTALL)
+_ANY_SCOPE = re.compile(r"^https://sunstone\.institute/rdf/scope/")
+_CONCEPTMAP = re.compile(r"^(https?://[^/]+)/conceptmap/(\d+)(?=[/#]|$)")
+_BASE_DECL = re.compile(r"^\s*(@base|base)\s*<", re.MULTILINE | re.IGNORECASE)
+#: The local stand-in for the graph IRI before a push (scope tools, SSSOM `curie_map`).
+PLACEHOLDER = "https://data.sunstone.institute/conceptmap/0"
+CMAP = "https://sunstone.institute/rdf/conceptmap#"
+
+
+class ConceptMapError(ValueError):
+    """The scope directory cannot be pushed as asked."""
+
+
+@dataclass(frozen=True)
+class ConceptMapPush:
+    """The outcome of a push.
+
+    Attributes:
+        conceptmap: The concept map id.
+        graph_iri: Its named graph, which is also the concept scheme IRI.
+        branch: Branch written.
+        triples: Triples in the pushed graph.
+        etag: Branch ETag after the write, unquoted.
+    """
+
+    conceptmap: int
+    graph_iri: str
+    branch: str
+    triples: int
+    etag: str
+
+
+def conceptmap_iri(n: int, base_iri: str | None = None) -> str:
+    """The graph IRI of concept map `n`: `{origin of BASE_IRI}/conceptmap/{n}`."""
+    parts = urlsplit(base_iri or get_settings().base_iri)
+    return f"{parts.scheme}://{parts.netloc}/conceptmap/{n}"
+
+
+def scheme_files(scope_dir: Path) -> list[Path]:
+    """The Turtle files of a scope directory: `scheme/*.ttl`, sorted."""
+    files = sorted((scope_dir / "scheme").glob("*.ttl"))
+    if not files:
+        raise ConceptMapError(f"no scheme/*.ttl under {scope_dir}")
+    return files
+
+
+def mappings_file(scope_dir: Path) -> Path | None:
+    """The scope directory's `scheme/mappings.sssom.tsv`, if it has one."""
+    path = scope_dir / "scheme" / "mappings.sssom.tsv"
+    return path if path.is_file() else None
+
+
+def check_branch(branch: str) -> None:
+    """Refuse `main`: a concept map is written to a data branch, then merged with `sunstone data branch merge`."""
+    if branch == "main":
+        raise ConceptMapError(
+            "concept maps are not written to main; push to a data branch (--branch, default: the current git "
+            "branch) and merge it with `sunstone data branch merge <branch>`"
+        )
+
+
+def content_namespace(n: int) -> str:
+    """The catalog namespace holding concept map `n`'s source content blobs."""
+    return f"shared/conceptmap_{n}"
+
+
+def named_conceptmaps(files: list[Path]) -> set[str]:
+    """Concept map graph IRIs the files already use, e.g. after an earlier rewrite."""
+    graph = _parse(files, PLACEHOLDER + "/")
+    return {m.group(0) for term in _iris(graph) if (m := _CONCEPTMAP.match(term)) and m.group(0) != PLACEHOLDER}
+
+
+def build(files: list[Path], graph_iri: str, mappings: Path | None = None) -> Graph:
+    """Parse `files` with base `{graph_iri}/`, rewrite scope IRIs onto `graph_iri`, and return the merged graph.
+
+    With `mappings` (a `mappings.sssom.tsv`), its rows and header are added in
+    SSSOM's RDF form, rewritten the same way (see `sunstone_data.sssom`).
+
+    Raises:
+        ConceptMapError: A file declares a base or has `file:` IRIs, a file
+            names another concept map, a scope IRI is left that the rewrite
+            does not cover, or the mappings do not match the `skos:*Match`
+            triples.
+    """
+    from rdflib import Graph, URIRef
+
+    from sunstone_data import sssom
+
+    def rewrite_iri(iri: str) -> str:
+        if m := _SCOPE.match(iri):
+            kind, rest = m.groups()
+            return graph_iri + ("" if kind == "concept" else "/ontology") + rest
+        if iri == PLACEHOLDER or iri.startswith(PLACEHOLDER + "/"):
+            return graph_iri + iri[len(PLACEHOLDER) :]
+        return iri
+
+    def rewrite(term):
+        if not isinstance(term, URIRef):
+            return term
+        iri = rewrite_iri(str(term))
+        return URIRef(graph_iri if iri == graph_iri + "/" else iri)
+
+    out = Graph()
+    for s, p, o in _parse(files, graph_iri + "/"):
+        out.add((rewrite(s), rewrite(p), rewrite(o)))
+    if mappings is not None:
+        try:
+            sssom.add_to_graph(sssom.read(mappings), out, graph_iri, rewrite_iri)
+        except sssom.SSSOMError as e:
+            raise ConceptMapError(f"{mappings}: {e}") from e
+
+    names = _iris(out)
+    others = {m.group(0) for t in names if (m := _CONCEPTMAP.match(t)) and m.group(0) != graph_iri}
+    if others:
+        raise ConceptMapError(f"files name another concept map: {', '.join(sorted(others))}")
+    leftover = sorted(t for t in names if _ANY_SCOPE.match(t))
+    if leftover:
+        raise ConceptMapError(f"scope IRIs with no mapping: {', '.join(leftover[:5])}")
+    return out
+
+
+def create(scope_dir: Path, branch: str, client: GraphClient | None = None) -> ConceptMapPush:
+    """Allocate a concept map and push `scope_dir` to it.
+
+    The files are parsed and checked before the id is allocated, so a bad
+    directory does not use one up.
+
+    Raises:
+        ConceptMapError: `branch` is main, or the files already name a
+            concept map (use `update`).
+    """
+    check_branch(branch)
+    files = scheme_files(scope_dir)
+    named = named_conceptmaps(files)
+    if named:
+        raise ConceptMapError(f"files already name {', '.join(sorted(named))}; use update")
+    mappings = mappings_file(scope_dir)
+    content_files(build(files, conceptmap_iri(0), mappings), scope_dir)  # validate before allocating
+
+    client = client or get_graph_client()
+    alloc = client.allocate_conceptmap()
+    n, graph_iri = alloc["conceptmap"], alloc["graph_iri"]
+    graph = build(files, graph_iri, mappings)
+    _push_content(client, n, branch, graph, scope_dir)
+    etag = _put(client, branch, graph_iri, graph, "*")
+    return ConceptMapPush(n, graph_iri, branch, len(graph), etag)
+
+
+def update(n: int, scope_dir: Path, branch: str, client: GraphClient | None = None) -> ConceptMapPush:
+    """Replace concept map `n` with `scope_dir`.
+
+    Raises:
+        ConceptMapError: `branch` is main, the concept map has no graph on
+            `branch` (a missing branch is first forked from main), or the
+            files name a different concept map.
+    """
+    check_branch(branch)
+    graph_iri = conceptmap_iri(n)
+    graph = build(scheme_files(scope_dir), graph_iri, mappings_file(scope_dir))
+    content_files(graph, scope_dir)
+
+    client = client or get_graph_client()
+    if branch not in {b["name"] for b in client.list_branches()}:
+        client.create_branch(branch)  # fork from main, where the concept map was merged
+    try:
+        _, etag = client.get_graph_with_etag(branch, graph_iri, accept=N_TRIPLES)
+    except NotFound:
+        raise ConceptMapError(f"concept map {n} has no graph on {branch}; use create") from None
+    _push_content(client, n, branch, graph, scope_dir)
+    etag = _put(client, branch, graph_iri, graph, etag)
+    return ConceptMapPush(n, graph_iri, branch, len(graph), etag)
+
+
+def sssom(n: int, branch: str, client: GraphClient | None = None) -> str:
+    """Concept map `n`'s mappings on `branch` as an SSSOM TSV file.
+
+    Fetches the named graph and runs the `/conceptmap/{n}/mappings` view
+    query on it locally, so any branch works (the view serves `main` only).
+
+    Raises:
+        ConceptMapError: The concept map has no graph on `branch`, or the
+            graph has no mapping set.
+    """
+    from rdflib import Graph
+
+    from sunstone_data import sssom as sssom_
+
+    graph_iri = conceptmap_iri(n)
+    client = client or get_graph_client()
+    try:
+        text = client.get_graph(branch, graph_iri, accept=N_TRIPLES)
+    except NotFound:
+        raise ConceptMapError(f"concept map {n} has no graph on {branch}") from None
+    try:
+        return sssom_.from_graph(Graph().parse(data=text, format="nt"), n, graph_iri)
+    except sssom_.SSSOMError as e:
+        raise ConceptMapError(str(e)) from e
+
+
+def content_files(graph: Graph, scope_dir: Path) -> dict[Path, list]:
+    """Content files of the graph's `cmap:Source`s that exist, each with the Sources naming it.
+
+    Raises:
+        ConceptMapError: A `cmap:contentPath` is absolute or leads out of
+            `scope_dir` (through `..` or a symlink).
+    """
+    from rdflib import RDF, URIRef
+
+    root = scope_dir.resolve()
+    out: dict[Path, list] = {}
+    for source in graph.subjects(RDF.type, URIRef(CMAP + "Source")):
+        for value in graph.objects(source, URIRef(CMAP + "contentPath")):
+            rel = Path(str(value))
+            path = (root / rel).resolve()
+            if rel.is_absolute() or not path.is_relative_to(root):
+                raise ConceptMapError(f"cmap:contentPath {str(value)!r} of {source} is outside {scope_dir}")
+            if path.is_file():
+                out.setdefault(path, []).append(source)
+    return out
+
+
+def _push_content(client: GraphClient, n: int, branch: str, graph: Graph, scope_dir: Path) -> None:
+    """Upload the content files as blobs and add `cmap:contentBlob` to their Sources.
+
+    The push API returns the existing push for the same namespace, branch and
+    files, so an unchanged scope uploads nothing.
+    """
+    import hashlib
+
+    from rdflib import URIRef
+    from sunstone.asset import AssetKind
+    from sunstone.push import PushError, PushOptions, PushPackage, PushResource, media_type_for, sanitize_segment
+
+    from sunstone_data.config import current_environment_name
+    from sunstone_data.push import push_package
+
+    files = content_files(graph, scope_dir)
+    if not files:
+        return
+    root = scope_dir.resolve()
+    resources: dict[str, PushResource] = {}
+    for path in sorted(files):
+        rel = path.relative_to(root).as_posix()
+        try:
+            name = sanitize_segment(path.stem)
+        except PushError as e:
+            raise ConceptMapError(f"{rel}: {e}") from e
+        if name in resources:
+            raise ConceptMapError(f"{rel} and {resources[name].slug} both map to blob name {name!r}")
+        data = path.read_bytes()
+        resources[name] = PushResource(
+            slug=rel,
+            name=name,
+            path=path,
+            kind=AssetKind.BLOB,
+            media_type=media_type_for(path),
+            sha256=hashlib.sha256(data).hexdigest(),
+            size=len(data),
+            metadata={"path": rel},
+        )
+    namespace = content_namespace(n)
+    package = PushPackage(f"sunstone:{namespace}", namespace, tuple(resources.values()), public=False)
+    # The caller chose the branch for the whole concept map; `yes` carries that to the blobs.
+    options = PushOptions(env=current_environment_name(), branch=branch, yes=True)
+    result = push_package(package, options, client=client)
+    iris = {d.name: d.iri for d in result.datasets if d.status != "failed" and d.iri}
+    if not result.ok or set(iris) != set(resources):
+        problems = "; ".join(f"{d.name}: {d.message or d.status}" for d in result.datasets if d.name not in iris)
+        raise ConceptMapError(f"content upload {result.push_id} to {namespace} failed: {problems or 'no result'}")
+    for name, r in resources.items():
+        for source in files[r.path]:
+            graph.add((source, URIRef(CMAP + "contentBlob"), URIRef(iris[name])))
+
+
+def _put(client: GraphClient, branch: str, graph_iri: str, graph: Graph, if_match: str) -> str:
+    body = graph.serialize(format="nt", encoding="utf-8")
+    try:
+        return client.put_graph(branch, graph_iri, body, if_match=if_match, content_type=N_TRIPLES)
+    except ConflictError as e:
+        # `*` is refused on a branch with no commits yet (head txn-0); a
+        # concurrent commit also lands here. Retry once with the current head.
+        return client.put_graph(branch, graph_iri, body, if_match=e.etag, content_type=N_TRIPLES)
+
+
+def _parse(files: list[Path], base: str) -> Graph:
+    """Parse each file with `base`, refusing files that set their own base or end up with `file:` IRIs."""
+    from rdflib import Graph, URIRef
+
+    graph = Graph()
+    for f in files:
+        try:
+            text = f.read_text(encoding="utf-8")
+            if _BASE_DECL.search(text):
+                raise ConceptMapError(f"{f}: declares @base/BASE; scope files use IRIs relative to the concept map")
+            part = Graph().parse(data=text, format="turtle", publicID=base)
+        except ConceptMapError:
+            raise
+        except Exception as e:
+            raise ConceptMapError(f"{f}: {e}") from e
+        if any(isinstance(t, URIRef) and str(t).startswith("file:") for triple in part for t in triple):
+            raise ConceptMapError(f"{f}: has file: IRIs; scope files use IRIs relative to the concept map")
+        graph += part
+    return graph
+
+
+def _iris(graph: Graph) -> set[str]:
+    """IRIs in `graph`, including `xsd:anyURI` literals such as SSSOM prefix namespaces."""
+    from rdflib import Literal, URIRef
+    from rdflib.namespace import XSD
+
+    return {
+        str(t)
+        for triple in graph
+        for t in triple
+        if isinstance(t, URIRef) or (isinstance(t, Literal) and t.datatype == XSD.anyURI)
+    }

{sunstone_data_platform-1.4.0 → sunstone_data_platform-1.5.0}/src/sunstone_data/graph/client.py

@@ -14,6 +14,7 @@ or the sentinel ``*`` for "whatever is current".
 from __future__ import annotations
 
 import fnmatch
+import json
 import re
 from collections.abc import Callable
 
@@ -107,11 +108,39 @@ class PushRejected(RuntimeError):
 
 
 class Unavailable(RuntimeError):
-    """graph SoR unavailable; safe to retry."""
+    """graph-server answered 503.
+
+    With no server message the text is the generic "safe to retry" line. When the
+    server gave a reason, the text is "graph-server unavailable: <reason>" and
+    makes no retry claim, because some 503s are configuration errors.
+    """
 
     def __init__(self, message: str = "graph SoR unavailable; safe to retry"):
         super().__init__(message)
 
+    @classmethod
+    def from_response(cls, resp: httpx.Response) -> "Unavailable":
+        """Build from a 503 response, using the server's reason when it sent one."""
+        detail = _server_message(resp)
+        if not detail:
+            return cls()
+        return cls(f"graph-server unavailable: {detail}")
+
+
+def _server_message(resp: httpx.Response) -> str:
+    """The JSON ``error`` string if the body has one, else the stripped text body."""
+    try:
+        text = resp.text.strip()
+    except Exception:
+        return ""
+    try:
+        body = json.loads(text)
+    except ValueError:
+        return text
+    if isinstance(body, dict) and isinstance(body.get("error"), str) and body["error"].strip():
+        return body["error"].strip()
+    return text
+
 
 # graph-server's default protected-ref globs (DP-SPEC-14 D9). The deployed
 # rules file may differ; this client only uses them to word its 403s.
@@ -447,7 +476,7 @@ class GraphClient:
         if status == 415:
             return UnsupportedMedia()
         if status == 503:
-            return Unavailable()
+            return Unavailable.from_response(resp)
         return None
 
 

{sunstone_data_platform-1.4.0 → sunstone_data_platform-1.5.0}/src/sunstone_pipeline/assets/mirrors.py

@@ -76,7 +76,7 @@ def build_mirror_asset(config: SourceConfig) -> dg.AssetsDefinition:
         new_hash = compute_checksum_bytes(raw)
 
         # Compare with stored hash
-        current_hash = iceberg.get_table_property(config.table_ref, "sunstone.import.content_hash")
+        current_hash = iceberg.get_table_property(config.table_ref, "sunstone.import.checksum")
 
         if new_hash == current_hash:
             context.log.info(f"No change for {config.table_ref} (hash: {new_hash[:12]}...)")

sunstone_data_platform-1.4.0/src/sunstone_data/conceptmap.py

@@ -1,233 +0,0 @@
-"""Publish a map-concepts scope directory as a concept map (DP-REQ-323).
-
-A scope directory written by `/ontology-engineering:map-concepts` holds the
-concept map in `scheme/*.ttl`. Its subjects use research-stack's
-`https://sunstone.institute/rdf/scope/<N>/concept…` and `…/ontology…` IRIs.
-The platform names them under the concept map's graph IRI instead, so they are
-rewritten on the way in: `…/concept` becomes the graph IRI (the scheme) and
-`…/ontology` becomes `{graph_iri}/ontology`. This is a stopgap until
-research-stack mints the platform IRIs itself (DP-160). Local files are never
-changed, so the same directory can be pushed again with `update`.
-
-- `create` allocates a new concept map (`POST /conceptmaps/`) and PUTs the
-  merged files to its named graph.
-- `update` replaces an existing concept map's named graph.
-- `sssom` writes a concept map's mappings back out as an SSSOM file.
-
-When the directory has `scheme/mappings.sssom.tsv`, its per-mapping metadata
-is pushed with the Turtle (see `sunstone_data.sssom`).
-"""
-
-from __future__ import annotations
-
-import re
-from dataclasses import dataclass
-from pathlib import Path
-from typing import TYPE_CHECKING
-from urllib.parse import urlsplit
-
-from sunstone_data.config import get_settings
-from sunstone_data.graph.client import N_TRIPLES, ConflictError, GraphClient, NotFound, get_graph_client
-
-if TYPE_CHECKING:
-    from rdflib import Graph
-
-_SCOPE = re.compile(r"^https://sunstone\.institute/rdf/scope/\d+/(concept|ontology)(.*)$", re.DOTALL)
-_ANY_SCOPE = re.compile(r"^https://sunstone\.institute/rdf/scope/")
-_CONCEPTMAP = re.compile(r"^(https?://[^/]+)/conceptmap/(\d+)(?=[/#]|$)")
-
-
-class ConceptMapError(ValueError):
-    """The scope directory cannot be pushed as asked."""
-
-
-@dataclass(frozen=True)
-class ConceptMapPush:
-    """The outcome of a push.
-
-    Attributes:
-        conceptmap: The concept map id.
-        graph_iri: Its named graph, which is also the concept scheme IRI.
-        branch: Branch written.
-        triples: Triples in the pushed graph.
-        etag: Branch ETag after the write, unquoted.
-    """
-
-    conceptmap: int
-    graph_iri: str
-    branch: str
-    triples: int
-    etag: str
-
-
-def conceptmap_iri(n: int, base_iri: str | None = None) -> str:
-    """The graph IRI of concept map `n`: `{origin of BASE_IRI}/conceptmap/{n}`."""
-    parts = urlsplit(base_iri or get_settings().base_iri)
-    return f"{parts.scheme}://{parts.netloc}/conceptmap/{n}"
-
-
-def scheme_files(scope_dir: Path) -> list[Path]:
-    """The Turtle files of a scope directory: `scheme/*.ttl`, sorted."""
-    files = sorted((scope_dir / "scheme").glob("*.ttl"))
-    if not files:
-        raise ConceptMapError(f"no scheme/*.ttl under {scope_dir}")
-    return files
-
-
-def mappings_file(scope_dir: Path) -> Path | None:
-    """The scope directory's `scheme/mappings.sssom.tsv`, if it has one."""
-    path = scope_dir / "scheme" / "mappings.sssom.tsv"
-    return path if path.is_file() else None
-
-
-def named_conceptmaps(files: list[Path]) -> set[str]:
-    """Concept map graph IRIs the files already use, e.g. after an earlier rewrite."""
-    graph = _parse(files)
-    return {m.group(0) for term in _iris(graph) if (m := _CONCEPTMAP.match(term))}
-
-
-def build(files: list[Path], graph_iri: str, mappings: Path | None = None) -> Graph:
-    """Parse `files`, rewrite scope IRIs onto `graph_iri`, and return the merged rdflib graph.
-
-    With `mappings` (a `mappings.sssom.tsv`), its rows and header are added in
-    SSSOM's RDF form, rewritten the same way (see `sunstone_data.sssom`).
-
-    Raises:
-        ConceptMapError: A file names another concept map, a scope IRI is
-            left that the rewrite does not cover, or the mappings do not
-            match the `skos:*Match` triples.
-    """
-    from rdflib import Graph, URIRef
-
-    from sunstone_data import sssom
-
-    def rewrite_iri(iri: str) -> str:
-        if m := _SCOPE.match(iri):
-            kind, rest = m.groups()
-            return graph_iri + ("" if kind == "concept" else "/ontology") + rest
-        return iri
-
-    def rewrite(term):
-        return URIRef(rewrite_iri(str(term))) if isinstance(term, URIRef) else term
-
-    out = Graph()
-    for s, p, o in _parse(files):
-        out.add((rewrite(s), rewrite(p), rewrite(o)))
-    if mappings is not None:
-        try:
-            sssom.add_to_graph(sssom.read(mappings), out, graph_iri, rewrite_iri)
-        except sssom.SSSOMError as e:
-            raise ConceptMapError(f"{mappings}: {e}") from e
-
-    names = _iris(out)
-    others = {m.group(0) for t in names if (m := _CONCEPTMAP.match(t)) and m.group(0) != graph_iri}
-    if others:
-        raise ConceptMapError(f"files name another concept map: {', '.join(sorted(others))}")
-    leftover = sorted(t for t in names if _ANY_SCOPE.match(t))
-    if leftover:
-        raise ConceptMapError(f"scope IRIs with no mapping: {', '.join(leftover[:5])}")
-    return out
-
-
-def create(scope_dir: Path, branch: str, client: GraphClient | None = None) -> ConceptMapPush:
-    """Allocate a concept map and push `scope_dir` to it.
-
-    The files are parsed and checked before the id is allocated, so a bad
-    directory does not use one up.
-
-    Raises:
-        ConceptMapError: The files already name a concept map (use `update`).
-    """
-    files = scheme_files(scope_dir)
-    named = named_conceptmaps(files)
-    if named:
-        raise ConceptMapError(f"files already name {', '.join(sorted(named))}; use update")
-    mappings = mappings_file(scope_dir)
-    build(files, conceptmap_iri(0), mappings)  # validate before allocating
-
-    client = client or get_graph_client()
-    alloc = client.allocate_conceptmap()
-    graph_iri = alloc["graph_iri"]
-    graph = build(files, graph_iri, mappings)
-    etag = _put(client, branch, graph_iri, graph, "*")
-    return ConceptMapPush(alloc["conceptmap"], graph_iri, branch, len(graph), etag)
-
-
-def update(n: int, scope_dir: Path, branch: str, client: GraphClient | None = None) -> ConceptMapPush:
-    """Replace concept map `n` with `scope_dir`.
-
-    Raises:
-        ConceptMapError: The concept map has no graph on `branch`, or the
-            files name a different concept map.
-    """
-    graph_iri = conceptmap_iri(n)
-    graph = build(scheme_files(scope_dir), graph_iri, mappings_file(scope_dir))
-
-    client = client or get_graph_client()
-    try:
-        _, etag = client.get_graph_with_etag(branch, graph_iri, accept=N_TRIPLES)
-    except NotFound:
-        raise ConceptMapError(f"concept map {n} has no graph on {branch}; use create") from None
-    etag = _put(client, branch, graph_iri, graph, etag)
-    return ConceptMapPush(n, graph_iri, branch, len(graph), etag)
-
-
-def sssom(n: int, branch: str, client: GraphClient | None = None) -> str:
-    """Concept map `n`'s mappings on `branch` as an SSSOM TSV file.
-
-    Fetches the named graph and runs the `/conceptmap/{n}/mappings` view
-    query on it locally, so any branch works (the view serves `main` only).
-
-    Raises:
-        ConceptMapError: The concept map has no graph on `branch`, or the
-            graph has no mapping set.
-    """
-    from rdflib import Graph
-
-    from sunstone_data import sssom as sssom_
-
-    graph_iri = conceptmap_iri(n)
-    client = client or get_graph_client()
-    try:
-        text = client.get_graph(branch, graph_iri, accept=N_TRIPLES)
-    except NotFound:
-        raise ConceptMapError(f"concept map {n} has no graph on {branch}") from None
-    try:
-        return sssom_.from_graph(Graph().parse(data=text, format="nt"), n, graph_iri)
-    except sssom_.SSSOMError as e:
-        raise ConceptMapError(str(e)) from e
-
-
-def _put(client: GraphClient, branch: str, graph_iri: str, graph: Graph, if_match: str) -> str:
-    body = graph.serialize(format="nt", encoding="utf-8")
-    try:
-        return client.put_graph(branch, graph_iri, body, if_match=if_match, content_type=N_TRIPLES)
-    except ConflictError as e:
-        # `*` is refused on a branch with no commits yet (head txn-0); a
-        # concurrent commit also lands here. Retry once with the current head.
-        return client.put_graph(branch, graph_iri, body, if_match=e.etag, content_type=N_TRIPLES)
-
-
-def _parse(files: list[Path]) -> Graph:
-    from rdflib import Graph
-
-    graph = Graph()
-    for f in files:
-        try:
-            graph.parse(f, format="turtle")
-        except Exception as e:
-            raise ConceptMapError(f"{f}: {e}") from e
-    return graph
-
-
-def _iris(graph: Graph) -> set[str]:
-    """IRIs in `graph`, including `xsd:anyURI` literals such as SSSOM prefix namespaces."""
-    from rdflib import Literal, URIRef
-    from rdflib.namespace import XSD
-
-    return {
-        str(t)
-        for triple in graph
-        for t in triple
-        if isinstance(t, URIRef) or (isinstance(t, Literal) and t.datatype == XSD.anyURI)
-    }