cf-runtime 0.1.8__py3-none-any.whl

cf_runtime/teardown.py

@@ -0,0 +1,237 @@
+"""Runtime-owned production teardown planning and transaction state."""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+from pathlib import Path
+import re
+import shutil
+import tempfile
+from typing import Mapping
+
+from .domain import RuntimeId
+from .lifecycle import ProductionRuntime
+from .paths import CogniflowHome
+from .semantics import recover_stopped, restore, status as semantic_status, uninstall as semantic_uninstall
+
+_DIGEST = re.compile(r"sha256:[0-9a-f]{64}\Z")
+_TOKEN = re.compile(r"[0-9a-f]{64}\Z")
+def _canonical(value: object) -> bytes:
+    return (json.dumps(value, sort_keys=True, separators=(",", ":")) + "\n").encode()
+
+
+def _digest(value: object) -> str:
+    return "sha256:" + hashlib.sha256(_canonical(value)).hexdigest()
+
+
+def _atomic(path: Path, value: dict[str, object]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    descriptor, name = tempfile.mkstemp(prefix=f".{path.name}.", dir=path.parent)
+    try:
+        with os.fdopen(descriptor, "wb") as stream:
+            stream.write(_canonical(value))
+            stream.flush()
+            os.fsync(stream.fileno())
+        os.replace(name, path)
+    finally:
+        Path(name).unlink(missing_ok=True)
+
+
+def plan(home: CogniflowHome) -> dict[str, object]:
+    paths = home.runtime(RuntimeId.PRODUCTION)
+    value = {
+        "schema": "cf.runtime.production-teardown-plan.v1",
+        "remove": [str(item) for item in (paths.state, paths.locks, paths.logs, paths.temp, paths.fuseki_config, paths.manifest)],
+        "retain": [str(home.tools / "java"), str(home.tools / "fuseki"), str(home.root / "data"), str(paths.fuseki_database), str(home.root)],
+    }
+    value["plan_digest"] = _digest(value)
+    return value
+
+
+def _path(home: CogniflowHome, transaction_id: str) -> Path:
+    if not _TOKEN.fullmatch(transaction_id):
+        raise ValueError("runtime teardown transaction id is invalid")
+    return home.root / "state" / "runtime-uninstall" / f"{transaction_id}.json"
+
+
+def _read(home: CogniflowHome, transaction_id: str) -> dict[str, object]:
+    path = _path(home, transaction_id)
+    raw = path.read_bytes()
+    value = json.loads(raw)
+    if not isinstance(value, dict) or raw != _canonical(value) or value.get("record_digest") != _digest({key: item for key, item in value.items() if key != "record_digest"}):
+        raise ValueError("runtime teardown transaction is invalid")
+    return value
+
+
+def _write(home: CogniflowHome, value: dict[str, object], phase: str) -> dict[str, object]:
+    updated = {**value, "phase": phase}
+    updated.pop("record_digest", None)
+    updated["record_digest"] = _digest(updated)
+    _atomic(_path(home, str(updated["transaction_id"])), updated)
+    return updated
+
+
+def _attestation(value: Mapping[str, object]) -> dict[str, object]:
+    receipt = value.get("semantic_receipt")
+    result = {
+        "schema": "cf.runtime.production-teardown-attestation.v1",
+        "phase": value["phase"],
+        "transaction_id": value["transaction_id"],
+        "nonce": value["nonce"],
+        "authority": value["authority"],
+        "preview_digest": value["preview_digest"],
+        "plan": value["plan"],
+        "semantic_graphs": value["semantic_graphs"],
+        "semantic_receipt": receipt,
+        "semantic_receipt_digest": _digest(receipt),
+        "transaction_digest": value["record_digest"],
+    }
+    return result
+
+
+def _verify_broad_stage(root: Path, target: Path) -> None:
+    preserved = {"environment", ".cogniflow-instance.json", ".cogniflow-profile-handoff.json", ".cogniflow-profile.json", ".cogniflow-profile-transition.json", "state"}
+    if not root.is_dir() or not target.is_file() or any(item.name not in preserved for item in root.iterdir()):
+        raise ValueError("installation broad cleanup is not complete")
+
+
+def _validate_binding(transaction_id: object, nonce: object, authority: object, preview_digest: object) -> tuple[str, str, dict[str, object], str]:
+    if not isinstance(transaction_id, str) or not _TOKEN.fullmatch(transaction_id) or not isinstance(nonce, str) or not _TOKEN.fullmatch(nonce):
+        raise ValueError("runtime teardown transaction binding is invalid")
+    if not isinstance(authority, dict) or authority.get("schema") != "cf.bootstrap.uninstall-authority.v1":
+        raise ValueError("runtime teardown authority is invalid")
+    if not isinstance(preview_digest, str) or not _DIGEST.fullmatch(preview_digest):
+        raise ValueError("runtime teardown preview binding is invalid")
+    return transaction_id, nonce, authority, preview_digest
+
+
+def prepare(home: CogniflowHome, *, transaction_id: object, nonce: object, authority: object, preview_digest: object, documents: object) -> dict[str, object]:
+    transaction_id, nonce, authority, preview_digest = _validate_binding(transaction_id, nonce, authority, preview_digest)
+    path = _path(home, transaction_id)
+    if path.exists():
+        raise ValueError("runtime teardown transaction already exists")
+    result = semantic_uninstall(home, documents) if documents else {"receipt": None, "graphs": [], "unrelated_graphs": []}
+    receipt = result.get("receipt")
+    try:
+        value = {
+            "schema": "cf.runtime.production-teardown-transaction.v1",
+            "phase": "prepared",
+            "transaction_id": transaction_id,
+            "nonce": nonce,
+            "authority": authority,
+            "preview_digest": preview_digest,
+            "plan": plan(home),
+            "documents": documents,
+            "semantic_graphs": sorted(str(item["graph"]) for item in result.get("graphs", [])),
+            "semantic_receipt": receipt,
+        }
+        value["record_digest"] = _digest(value)
+        _atomic(path, value)
+    except Exception:
+        if isinstance(receipt, Mapping):
+            restore(home, dict(receipt))
+        raise
+    return _attestation(value)
+
+
+def _verify_effects(home: CogniflowHome, value: Mapping[str, object]) -> None:
+    if value.get("plan") != plan(home):
+        raise ValueError("runtime teardown plan changed")
+    phase = value.get("phase")
+    if phase == "prepared":
+        documents = value.get("documents")
+        if documents:
+            semantic = semantic_status(home, documents)
+            if any(item.get("state") != "missing" for item in semantic.get("graphs", [])):
+                raise ValueError("runtime teardown semantic effects are not present")
+    elif phase == "stopped":
+        observed = ProductionRuntime(home).status()
+        if observed.get("running") is not False or observed.get("ready") is not False:
+            raise ValueError("runtime teardown stop effect is not present")
+    elif phase in {"cleaned", "finalized"}:
+        if any(Path(item).exists() for item in value["plan"]["remove"]):
+            raise ValueError("runtime teardown cleanup effect is not present")
+        if phase == "finalized":
+            authority = value["authority"]
+            root = Path(str(authority["installation_root"]))
+            target = Path(str(authority["target_python"]))
+            _verify_broad_stage(root, target)
+    else:
+        raise ValueError("runtime teardown phase is invalid")
+
+
+def attest(home: CogniflowHome, expected: object) -> dict[str, object]:
+    if not isinstance(expected, dict) or not isinstance(expected.get("transaction_id"), str):
+        raise ValueError("runtime teardown attestation request is invalid")
+    value = _read(home, expected["transaction_id"])
+    actual = _attestation(value)
+    if actual != expected:
+        raise ValueError("runtime teardown transaction does not match")
+    _verify_effects(home, value)
+    return actual
+
+
+def stop(home: CogniflowHome, expected: object, *, timeout: float) -> dict[str, object]:
+    attest(home, expected)
+    value = _read(home, expected["transaction_id"])
+    if value["phase"] != "prepared":
+        raise ValueError("runtime teardown transaction is not prepared")
+    ProductionRuntime(home).stop(timeout=timeout)
+    updated = _write(home, value, "stopped")
+    _verify_effects(home, updated)
+    return _attestation(updated)
+
+
+def cleanup(home: CogniflowHome, expected: object) -> dict[str, object]:
+    attest(home, expected)
+    value = _read(home, expected["transaction_id"])
+    if value["phase"] != "stopped":
+        raise ValueError("runtime teardown transaction is not stopped")
+    for item in value["plan"]["remove"]:
+        path = Path(item)
+        if path.is_symlink():
+            raise ValueError("runtime teardown path is unsafe")
+        if path.is_dir():
+            shutil.rmtree(path)
+        elif path.exists():
+            path.unlink()
+    updated = _write(home, value, "cleaned")
+    _verify_effects(home, updated)
+    return _attestation(updated)
+
+
+def finalize(home: CogniflowHome, expected: object) -> dict[str, object]:
+    if not isinstance(expected, dict) or not isinstance(expected.get("transaction_id"), str):
+        raise ValueError("runtime teardown finalization request is invalid")
+    value = _read(home, expected["transaction_id"])
+    if value["phase"] == "finalized":
+        actual = _attestation(value)
+        stable = {"transaction_id", "nonce", "authority", "preview_digest", "plan", "semantic_graphs", "semantic_receipt", "semantic_receipt_digest"}
+        if expected.get("phase") != "cleaned" or any(expected.get(key) != actual.get(key) for key in stable):
+            raise ValueError("runtime final cleanup retry does not match")
+        _verify_effects(home, value)
+        return actual
+    attest(home, expected)
+    if value["phase"] != "cleaned":
+        raise ValueError("runtime teardown transaction is not cleaned")
+    authority = value["authority"]
+    _verify_broad_stage(Path(str(authority["installation_root"])), Path(str(authority["target_python"])))
+    finalized = _write(home, value, "finalized")
+    _verify_effects(home, finalized)
+    return _attestation(finalized)
+
+
+def recover(home: CogniflowHome, expected: object, *, timeout: float) -> dict[str, object]:
+    if not isinstance(expected, dict) or not isinstance(expected.get("transaction_id"), str):
+        raise ValueError("runtime teardown recovery request is invalid")
+    value = _read(home, expected["transaction_id"])
+    if _attestation(value) != expected or value["phase"] not in {"prepared", "stopped"}:
+        raise ValueError("runtime teardown recovery transaction does not match")
+    receipt = value.get("semantic_receipt")
+    if isinstance(receipt, Mapping):
+        restored = (recover_stopped(home, dict(receipt), timeout=timeout) if value["phase"] == "stopped" else restore(home, dict(receipt)))["restored"]
+    else:
+        restored = []
+    _path(home, str(value["transaction_id"])).unlink()
+    return {"schema": "cf.runtime.production-teardown-recovery.v1", "status": "recovered", "transaction_id": value["transaction_id"], "restored": restored}

cf_runtime-0.1.8.dist-info/METADATA

@@ -0,0 +1,35 @@
+Metadata-Version: 2.4
+Name: cf-runtime
+Version: 0.1.8
+Summary: Local Cogniflow runtime bootstrap and lifecycle provider.
+Author: Cogniflow Maintainers
+License: GPL-3
+Requires-Python: >=3.11
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == 'test'
+Requires-Dist: rdflib>=7; extra == 'test'
+Description-Content-Type: text/markdown
+
+# cf-runtime
+
+`cf_runtime` defines Cogniflow runtime identity, filesystem layout, managed tools, manifests, connection targets, and process lifecycle. Other implementation packages cross its installed process boundary with validated JSON rather than importing runtime internals.
+
+## Runtime model
+
+The closed runtime identities are `development` and `production`. Development uses an explicit source tree and semantic seed with managed Java and Fuseki on loopback port 3030. Production uses an explicitly installed instance outside `.cogniflow`, isolated port 3130, the instance's canonical Python executable, and its installed native MCP service executable.
+
+`CogniflowHome` and `RuntimePaths` own all `.cogniflow` paths. `RuntimeManifest` schema version 2 is strict, deterministic, pair-validated, and atomically written. Unknown fields and obsolete schemas are rejected. Development lifecycle operations use an exclusive canonical lock and publish process and readiness identity atomically.
+
+## Process protocol
+
+`cf-runtime-bootstrap` reads one `cf.runtime.bootstrap.v1` JSON request per stdin line and writes one response per stdout line. Supported methods include target resolution, production preflight, managed-tool provisioning, and development prepare/start/status/stop. The principal outputs are canonical runtime targets, verified managed-tool paths, production composition evidence, and development lifecycle state.
+
+Production preflight validates an installed instance and publishes runtime composition but never starts a process. Development preparation receives its source root and semantic seed explicitly. A resolved development target uses stdio and exposes only `COGNIFLOW_RUNTIME_MANIFEST` to the child process.
+
+## Managed tools
+
+`managed-tools/provision` accepts `cf.runtime.managed-tools.request.v1` with exact Java and Fuseki versions and returns `cf.runtime.managed-tools.result.v1`. Acquisition is HTTPS-only for production URLs, cache-backed, locked, exact-size and SHA-256 verified, archive-safe, version-checked, and idempotent. Provisioning does not disable TLS verification and does not start Fuseki.
+
+## Boundaries
+
+The runtime package does not choose installation profiles, resolve Python artifacts, create the target instance, or own service-level install, repair, transition, and uninstall policy. Bootstrap components may invoke managed-tool provisioning before Fuseki exists; local profile and capability discovery therefore remains outside the runtime and does not depend on SPARQL. Package semantics are under `src/cf_runtime/semantics/`.

cf_runtime-0.1.8.dist-info/RECORD

@@ -0,0 +1,17 @@
+cf_runtime/__init__.py,sha256=Ou6XYgiE4drrE3_lsEQWGa4RhpF_E7FdjVAXFiM-i7o,1923
+cf_runtime/bootstrap.py,sha256=OrJlTaPV0EI5-a6rt_W0FO0AzyQKK_3RBe7RQRgWojc,20726
+cf_runtime/domain.py,sha256=jst5Dgj2OU7unCWkbYf0bxTuh4YIhJtoPZK7zoF6T9A,538
+cf_runtime/installed_seed.py,sha256=qdubfXabUKZP7sR0prrKgZJ1rkpFS5LejwXU4n9jUoA,2316
+cf_runtime/lifecycle.py,sha256=cHkBYFMTY0cgwSQ4QlSOOwkyMSeicSsOZqFNzIGO9jI,26310
+cf_runtime/locking.py,sha256=qYPiaQaWjAdqKfE4hcdp0uqss6lVKtAvryBaTJOFleo,2153
+cf_runtime/managed_tools.py,sha256=kCDSqa_u4S2jt-NEudTdUelxCMexgJeucldQ5SnMHlk,18776
+cf_runtime/manifest.py,sha256=VebMK7dNiBXxH8ANJEiUmeDYl8Qk5Vlm__HNO4BNAs0,28543
+cf_runtime/paths.py,sha256=yvo1OxMF3d2DhxqjKhl38gQ_CXeBuJVcFEIsUcXNimA,8105
+cf_runtime/semantics.py,sha256=ttDiDmDEhYc-Bpi_VapD2DLm5z6tGk38ahvplyvQmc8,22920
+cf_runtime/target.py,sha256=_JIDBQ-gTkGlhBg9Rhsw0DoyWm5HU8u6FwEc4_oJ7SY,7212
+cf_runtime/teardown.py,sha256=O2uCr7HJ3TFJOB816Q92-T0jsaKlai5-V0mt_MJo-Yo,11087
+cf_runtime/semantics/package.trig,sha256=te-b3sDlVxVjwxCiUfbVmvfOj7ITG7_ORWscYKQ8GtE,1499
+cf_runtime-0.1.8.dist-info/METADATA,sha256=NZltoPiVPRlk2zpFxVc3BKF76WJPW9R08wFRmzmrA9U,2915
+cf_runtime-0.1.8.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+cf_runtime-0.1.8.dist-info/entry_points.txt,sha256=lIxZHOM0y9zBbG3t7kQ-jm6AU60PhynIJt0_AEjxxkw,136
+cf_runtime-0.1.8.dist-info/RECORD,,

cf_runtime-0.1.8.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

cf_runtime-0.1.8.dist-info/entry_points.txt

@@ -0,0 +1,5 @@
+[console_scripts]
+cf-runtime-bootstrap = cf_runtime.bootstrap:main
+
+[cogniflow.semantic_sources]
+cf-runtime = cf_runtime:semantic_files