cf-runtime 0.1.8__py3-none-any.whl

cf_runtime/paths.py

@@ -0,0 +1,257 @@
+"""Canonical filesystem layout and its only directory-creation API."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+import re
+
+from .domain import RuntimeId
+
+_IDENTIFIER = re.compile(r"[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?\Z")
+_VERSION_IDENTIFIER = re.compile(r"[A-Za-z0-9](?:[A-Za-z0-9._+-]*[A-Za-z0-9])?\Z")
+
+
+def _absolute(path: Path) -> Path:
+    return path.expanduser().resolve(strict=False)
+
+
+def _under(path: Path, parent: Path, *, label: str) -> Path:
+    resolved = _absolute(path)
+    try:
+        resolved.relative_to(parent)
+    except ValueError as error:
+        raise ValueError(f"{label} must be below Cogniflow home") from error
+    return resolved
+
+
+def _identifier(value: str, label: str) -> str:
+    if not isinstance(value, str) or not _IDENTIFIER.fullmatch(value):
+        raise ValueError(f"invalid {label}: {value!r}")
+    return value
+
+
+def _version_identifier(value: str, label: str) -> str:
+    if not isinstance(value, str) or not _VERSION_IDENTIFIER.fullmatch(value):
+        raise ValueError(f"invalid {label}: {value!r}")
+    return value
+
+
+@dataclass(frozen=True, slots=True)
+class CogniflowHome:
+    root: Path
+
+    def __post_init__(self) -> None:
+        root = _absolute(Path(self.root))
+        if root == Path(root.anchor):
+            raise ValueError("Cogniflow home cannot be a filesystem root")
+        object.__setattr__(self, "root", root)
+
+    @classmethod
+    def default(cls) -> CogniflowHome:
+        return cls(Path.home() / ".cogniflow")
+
+    @classmethod
+    def at(cls, root: str | Path) -> CogniflowHome:
+        return cls(Path(root))
+
+    @property
+    def tools(self) -> Path:
+        return self.root / "tools"
+
+    @property
+    def releases(self) -> Path:
+        return self.root / "releases"
+
+    tools_root = tools
+    releases_root = releases
+
+    def runtime(self, runtime_id: RuntimeId) -> RuntimePaths:
+        if not isinstance(runtime_id, RuntimeId):
+            raise TypeError("runtime_id must be a RuntimeId")
+        return RuntimePaths(self, runtime_id)
+
+    def fuseki_install(self, version: str) -> Path:
+        return self.tools / "fuseki" / _version_identifier(version, "Fuseki version")
+
+    def java_install(self, version: str) -> Path:
+        return self.tools / "java" / _version_identifier(version, "Java version")
+
+    def ensure_fuseki_install(self, version: str) -> Path:
+        path = self.fuseki_install(version)
+        path.mkdir(parents=True, exist_ok=True)
+        return path
+
+    def ensure_java_install(self, version: str) -> Path:
+        path = self.java_install(version)
+        path.mkdir(parents=True, exist_ok=True)
+        return path
+
+    def release(self, version: str) -> Path:
+        return self.releases / _version_identifier(version, "release version")
+
+    def ensure(self) -> Path:
+        self.root.mkdir(parents=True, exist_ok=True)
+        return self.root
+
+    def ensure_tools(self) -> Path:
+        self.tools.mkdir(parents=True, exist_ok=True)
+        return self.tools
+
+    @property
+    def tool_cache(self) -> Path:
+        return self.root / "cache" / "downloads"
+
+    @property
+    def tool_locks(self) -> Path:
+        return self.root / "locks" / "managed-tools.lock"
+
+    @property
+    def tool_state(self) -> Path:
+        return self.root / "state" / "managed-tools"
+
+    def ensure_releases(self) -> Path:
+        self.releases.mkdir(parents=True, exist_ok=True)
+        return self.releases
+
+    def ensure_release(self, version: str) -> Path:
+        path = self.release(version)
+        path.mkdir(parents=True, exist_ok=True)
+        return path
+
+    def validate_path(self, path: str | Path, *, label: str = "path") -> Path:
+        return _under(Path(path), self.root, label=label)
+
+
+@dataclass(frozen=True, slots=True)
+class RuntimePaths:
+    home: CogniflowHome
+    runtime_id: RuntimeId
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "runtime_id", RuntimeId(self.runtime_id))
+
+    @property
+    def runtime_root(self) -> Path:
+        return self.home.root / "runtimes" / self.runtime_id.value
+
+    @property
+    def state(self) -> Path:
+        return self.runtime_root / "state"
+
+    @property
+    def locks(self) -> Path:
+        return self.runtime_root / "locks"
+
+    @property
+    def lifecycle_lock(self) -> Path:
+        return self.locks / "lifecycle.lock"
+
+    @property
+    def logs(self) -> Path:
+        return self.runtime_root / "logs"
+
+    @property
+    def temp(self) -> Path:
+        return self.runtime_root / "temp"
+
+    @property
+    def fuseki(self) -> Path:
+        return self.runtime_root / "fuseki"
+
+    @property
+    def fuseki_config(self) -> Path:
+        return self.fuseki / "config"
+
+    @property
+    def fuseki_database(self) -> Path:
+        return self.fuseki / "database"
+
+    @property
+    def fuseki_server_config(self) -> Path:
+        return self.fuseki_config / "server.ttl"
+
+    @property
+    def data(self) -> Path:
+        return self.home.root / "data" / self.runtime_id.value
+
+    @property
+    def pipelines(self) -> Path:
+        return self.data / "pipelines"
+
+    @property
+    def results(self) -> Path:
+        return self.data / "results"
+
+    @property
+    def artifacts(self) -> Path:
+        return self.data / "artifacts"
+
+    @property
+    def manifest(self) -> Path:
+        return self.runtime_root / "runtime.toml"
+
+    @property
+    def identity(self) -> Path:
+        return self.state / "identity.json"
+
+    @property
+    def lifecycle_state(self) -> Path:
+        return self.state / "fuseki.json"
+
+    # Explicit *_dir aliases make call sites unambiguous without changing layout.
+    state_dir = state
+    locks_dir = locks
+    logs_dir = logs
+    temp_dir = temp
+    fuseki_config_dir = fuseki_config
+    fuseki_database_dir = fuseki_database
+    data_root = data
+    pipelines_dir = pipelines
+    results_dir = results
+    artifacts_dir = artifacts
+    manifest_file = manifest
+
+    def pipeline_run_dir(self, pipeline_id: str, run_id: str) -> Path:
+        pipeline = _identifier(pipeline_id, "pipeline identifier")
+        run = _identifier(run_id, "run identifier")
+        return self.pipelines / pipeline / run
+
+    def result_run_dir(self, pipeline_id: str, run_id: str) -> Path:
+        return self.results / _identifier(pipeline_id, "pipeline identifier") / _identifier(run_id, "run identifier")
+
+    def artifact_run_dir(self, pipeline_id: str, run_id: str) -> Path:
+        return self.artifacts / _identifier(pipeline_id, "pipeline identifier") / _identifier(run_id, "run identifier")
+
+    def validate(self, path: str | Path) -> Path:
+        resolved = self.home.validate_path(path)
+        for root in (self.runtime_root, self.data):
+            try:
+                resolved.relative_to(root)
+                return resolved
+            except ValueError:
+                continue
+        raise ValueError("path does not belong to this runtime")
+
+    def ensure_directories(self) -> None:
+        for path in (
+            self.state, self.locks, self.logs, self.temp,
+            self.fuseki_config, self.fuseki_database,
+            self.pipelines, self.results, self.artifacts,
+        ):
+            path.mkdir(parents=True, exist_ok=True)
+
+    def ensure_pipeline_run(self, pipeline_id: str, run_id: str) -> Path:
+        path = self.pipeline_run_dir(pipeline_id, run_id)
+        path.mkdir(parents=True, exist_ok=True)
+        return path
+
+    def ensure_result_run(self, pipeline_id: str, run_id: str) -> Path:
+        path = self.result_run_dir(pipeline_id, run_id)
+        path.mkdir(parents=True, exist_ok=True)
+        return path
+
+    def ensure_artifact_run(self, pipeline_id: str, run_id: str) -> Path:
+        path = self.artifact_run_dir(pipeline_id, run_id)
+        path.mkdir(parents=True, exist_ok=True)
+        return path

cf_runtime/semantics/package.trig

@@ -0,0 +1,36 @@
+@prefix cfpkg: <https://cogniflow.odea-project.org/cf#> .
+@prefix pkg: <urn:cf:pkg:> .
+@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
+@prefix skos: <http://www.w3.org/2004/02/skos/core#> .
+
+pkg:cf_runtime {
+    pkg:cf_runtime
+        a cfpkg:CfPackage ;
+        cfpkg:hasPackageManifest [
+            a cfpkg:PackageManifest ;
+            cfpkg:hasDistributionName [
+                a cfpkg:DistributionName ;
+                rdf:value "cf-runtime"
+            ] ;
+            cfpkg:hasPythonPackageName [
+                a cfpkg:PythonPackageName ;
+                rdf:value "cf_runtime"
+            ] ;
+            cfpkg:hasPackageVersion [
+                a cfpkg:PackageVersion ;
+                rdf:value "0.1.8"
+            ] ;
+            cfpkg:hasImplementationLanguage [
+                a cfpkg:ImplementationLanguage ;
+                rdf:value "Python"
+            ]
+        ] ;
+        cfpkg:hasPackageRole [
+            a cfpkg:PackageRole ;
+            rdf:value cfpkg:SpecificationPackageRole
+        ] ;
+        skos:prefLabel "cf_runtime" ;
+        skos:definition "Standalone provider for Cogniflow runtime paths, manifests, identity, and development lifecycle control." ;
+        skos:scopeNote "Exposes a local pre-runtime bootstrap protocol and is not a Fuseki-backed ServiceOperation." ;
+        skos:example "Consumers invoke cf-runtime-bootstrap and validate its plain JSON target response without importing cf_runtime." .
+}