cf-runtime 0.1.8__py3-none-any.whl

cf_runtime/manifest.py

@@ -0,0 +1,464 @@
+"""Strict runtime manifest model and deterministic, atomic TOML representation."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import hashlib
+import ipaddress
+import json
+import os
+from pathlib import Path
+import stat
+import re
+from types import MappingProxyType
+from typing import Mapping
+import tomllib
+
+from .domain import EnvironmentKind, McpTransport, RuntimeId, SourceKind
+from .paths import CogniflowHome
+
+SCHEMA_VERSION = 2
+DEFAULT_DEVELOPMENT_FUSEKI_PORT = 3030
+DEFAULT_PRODUCTION_FUSEKI_PORT = 3130
+DEFAULT_RUNTIME_VERSION = "0.1.0"
+DEFAULT_TOOL_VERSIONS = MappingProxyType({"fuseki": "6.0.0", "java": "21.0.10+7"})
+DEFAULT_DEVELOPMENT_MCP_COMMAND = (
+    "cargo", "run", "--quiet", "--manifest-path",
+    "stonecastle/cf_service_mcp_server/Cargo.toml", "--bin", "cf-service-mcp-server",
+)
+_BASE_TOP_KEYS = {"schema", "runtime", "paths", "source", "tools", "mcp", "fuseki", "public_gateway", "lifecycle", "versions"}
+_TABLE_KEYS = {
+    "schema": {"version"}, "runtime": {"id", "kind"},
+    "paths": {"home", "runtime", "data"}, "source": {"kind", "root"},
+    "mcp": {"transport", "command", "executable"},
+    "fuseki": {"bind", "port", "dataset", "config"},
+    "public_gateway": {"bind"}, "lifecycle": {"owner"},
+    "versions": {"semantic", "runtime", "release"},
+    "installation": {"root", "environment", "python"},
+    "instance": {"marker", "state", "plan_digest", "artifact_set_digest", "native_mcp_distribution", "native_mcp_version"},
+}
+_REQUIRED = {
+    "schema": {"version"}, "runtime": {"id", "kind"},
+    "paths": {"home", "runtime", "data"}, "source": {"kind", "root"},
+    "fuseki": {"bind", "port", "dataset", "config"},
+    "lifecycle": {"owner"},
+}
+_DATASET_NAME = re.compile(r"[A-Za-z0-9][A-Za-z0-9_-]*\Z")
+
+
+def _text(value: object, label: str) -> None:
+    if not isinstance(value, str) or not value.strip():
+        raise ValueError(f"{label} cannot be empty")
+
+
+def _loopback(value: str, label: str) -> None:
+    try:
+        address = ipaddress.ip_address(value)
+    except ValueError as error:
+        raise ValueError(f"{label} must be a loopback IP address") from error
+    if not address.is_loopback:
+        raise ValueError(f"{label} must be a loopback IP address")
+
+
+def _atomic_text(path: Path, content: str) -> None:
+    temporary = path.with_name(f".{path.name}.{os.getpid()}.tmp")
+    try:
+        with temporary.open("w", encoding="utf-8", newline="\n") as stream:
+            stream.write(content)
+            stream.flush()
+            os.fsync(stream.fileno())
+        os.replace(temporary, path)
+    finally:
+        temporary.unlink(missing_ok=True)
+
+
+def _same_path(left: Path, right: Path) -> bool:
+    left_value = os.path.normcase(str(left.resolve(strict=False)))
+    right_value = os.path.normcase(str(right.resolve(strict=False)))
+    return left_value == right_value
+
+
+def _strict_path(value: str | Path, label: str) -> Path:
+    path = Path(value).expanduser()
+    if not path.is_absolute() or path == Path(path.anchor) or any(part in {".", ".."} for part in path.parts):
+        raise ValueError(f"{label} must be an absolute normalized path")
+    current = Path(path.anchor)
+    for part in path.parts[1:]:
+        current /= part
+        try:
+            info = current.lstat()
+        except FileNotFoundError:
+            continue
+        if current.is_symlink() or (os.name == "nt" and getattr(info, "st_file_attributes", 0) & 0x400):
+            raise ValueError(f"{label} contains a redirecting link or reparse point")
+    return path
+
+
+def _real_file(path: Path, label: str) -> None:
+    try:
+        info = path.lstat()
+    except OSError as error:
+        raise ValueError(f"{label} is missing") from error
+    if not stat.S_ISREG(info.st_mode) or path.is_symlink() or (os.name == "nt" and getattr(info, "st_file_attributes", 0) & 0x400):
+        raise ValueError(f"{label} must be a regular non-link file")
+    if not _same_path(path, path.resolve(strict=True)):
+        raise ValueError(f"{label} is not canonical")
+
+
+def _below(path: Path, parent: Path, label: str) -> None:
+    if not path.is_absolute() or path == path.anchor:
+        raise ValueError(f"{label} must be an absolute path")
+    try:
+        path.relative_to(parent)
+    except ValueError as error:
+        raise ValueError(f"{label} must be below its declared root") from error
+
+
+def _validate_installed_paths(manifest: RuntimeManifest) -> None:
+    assert manifest.installation_root is not None
+    assert manifest.environment_root is not None
+    assert manifest.python_executable is not None
+    assert manifest.mcp_executable is not None
+    assert manifest.instance_marker is not None
+    install = manifest.installation_root
+    environment = manifest.environment_root
+    scripts = environment / ("Scripts" if os.name == "nt" else "bin")
+    _real_file(manifest.python_executable, "target Python executable")
+    _real_file(manifest.mcp_executable, "installed MCP executable")
+    if not install.is_dir() or install.is_symlink() or not environment.is_dir() or environment.is_symlink():
+        raise ValueError("installed roots must be real directories")
+    _below(environment, install, "target environment")
+    _below(manifest.python_executable, environment, "target Python executable")
+    _below(manifest.mcp_executable, scripts, "installed MCP executable")
+    if not _same_path(manifest.source_root, install):
+        raise ValueError("production source root must equal the external installation root")
+    if (_same_path(install, manifest.home_root) or _same_path(environment, manifest.home_root)
+            or _below_or_equal(install, manifest.home_root) or _below_or_equal(environment, manifest.home_root)):
+        raise ValueError("installation root and target environment must be outside Cogniflow home")
+    if not _same_path(manifest.instance_marker.parent, install):
+        raise ValueError("instance marker must be directly below installation root")
+    _real_file(manifest.instance_marker, "SCB-05 instance marker")
+    try:
+        marker = json.loads(manifest.instance_marker.read_text(encoding="utf-8"))
+    except (OSError, UnicodeDecodeError, json.JSONDecodeError) as error:
+        raise ValueError("SCB-05 instance marker is invalid") from error
+    schema = marker.get("schema") if isinstance(marker, dict) else None
+    if schema == "cf.bootstrap.instance-marker.v1":
+        fields = {"schema", "instance_id", "installation_root", "environment_root", "python_executable",
+                  "plan_digest", "artifact_set_digest", "installed_distributions", "state"}
+    elif schema == "cf.bootstrap.instance-marker.v2":
+        fields = {"schema", "instance_id", "installation_root", "environment_root", "python_executable",
+                  "profile", "plan_digest", "profile_digest", "catalog_digest", "selection_digest",
+                  "artifact_set_digest", "installed_distributions", "recovery_manifest_path",
+                  "recovery_manifest_digest"}
+    else:
+        raise ValueError("SCB-05 instance marker schema is unsupported")
+    if set(marker) != fields:
+        raise ValueError("SCB-05 instance marker fields are invalid")
+    expected = {"plan_digest": manifest.plan_digest, "artifact_set_digest": manifest.artifact_set_digest}
+    bound_paths = ("installation_root", install), ("environment_root", environment), ("python_executable", manifest.python_executable)
+    if (not isinstance(marker.get("instance_id"), str) or not _valid_marker_identifier(marker["instance_id"])
+            or (schema == "cf.bootstrap.instance-marker.v1" and marker["state"] != "ready")
+            or (schema == "cf.bootstrap.instance-marker.v2" and (
+                not isinstance(marker["profile"], str) or not _valid_profile(marker["profile"])
+                or not _valid_digest(marker["profile_digest"])
+                or not _valid_digest(marker["catalog_digest"])
+                or not _valid_digest(marker["selection_digest"])))
+            or any(marker.get(key) != value for key, value in expected.items())
+            or not _valid_digest(manifest.plan_digest) or not _valid_digest(manifest.artifact_set_digest)
+            or any(not isinstance(marker.get(key), str) or not _bound_marker_path(marker[key], value) for key, value in bound_paths)):
+        raise ValueError("SCB-05 instance marker is not bound to this production composition")
+    if schema == "cf.bootstrap.instance-marker.v2":
+        recovery_manifest = install / "state" / "minimum-service-plane" / "recovery-manifest.json"
+        if (not _bound_marker_path(marker["recovery_manifest_path"], recovery_manifest)
+                or not _valid_digest(marker["recovery_manifest_digest"])):
+            raise ValueError("SCB-05 instance marker recovery authority is invalid")
+        _real_file(recovery_manifest, "SCB-13 recovery manifest")
+        if marker["recovery_manifest_digest"] != "sha256:" + hashlib.sha256(recovery_manifest.read_bytes()).hexdigest():
+            raise ValueError("SCB-05 instance marker recovery authority is not bound to retained state")
+    installed = marker.get("installed_distributions")
+    if (not isinstance(installed, list) or any(
+        not isinstance(item, dict) or set(item) != {"name", "version"}
+        or not isinstance(item["name"], str) or not _valid_marker_identifier(item["name"])
+        or not isinstance(item["version"], str) or not _valid_marker_version(item["version"])
+        for item in installed
+    ) or [item["name"].lower() for item in installed] != sorted({item["name"].lower() for item in installed})
+            or len({item["name"].lower() for item in installed}) != len(installed)
+            or not any(item["name"] == manifest.native_mcp_distribution and item["version"] == manifest.native_mcp_version for item in installed)):
+        raise ValueError("SCB-05 marker does not contain the installed native MCP distribution")
+
+
+def _bound_marker_path(value: object, expected: Path) -> bool:
+    if not isinstance(value, str):
+        return False
+    path = Path(value)
+    return path.is_absolute() and not any(part in {".", ".."} for part in path.parts) and _same_path(path, expected)
+
+
+def _valid_marker_identifier(value: str) -> bool:
+    return bool(value) and value[0].isalnum() and value[-1].isalnum() and all(character.isascii() and (character.isalnum() or character in ".-_") for character in value)
+
+
+def _valid_marker_version(value: str) -> bool:
+    return bool(value) and value[0].isdigit() and all(character.isascii() and (character.isalnum() or character in ".!+_-") for character in value)
+
+
+def _valid_digest(value: object) -> bool:
+    return isinstance(value, str) and len(value) == 71 and value.startswith("sha256:") and all(character in "0123456789abcdef" for character in value[7:])
+
+
+def _valid_profile(value: str) -> bool:
+    scheme, separator, rest = value.partition(":")
+    return bool(separator and rest and scheme[0].isalpha() and all(character.isascii() and (character.isalnum() or character in "+.-") for character in scheme) and not any(character.isspace() for character in rest))
+
+
+def _below_or_equal(path: Path, parent: Path) -> bool:
+    return _same_path(path, parent) or parent in path.parents
+
+
+@dataclass(frozen=True, slots=True)
+class RuntimeManifest:
+    runtime_id: RuntimeId
+    environment_kind: EnvironmentKind
+    home_root: Path
+    runtime_root: Path
+    data_root: Path
+    source_kind: SourceKind
+    source_root: Path
+    tool_versions: Mapping[str, str]
+    mcp_transport: McpTransport
+    mcp_command: tuple[str, ...] | None
+    fuseki_bind: str
+    fuseki_port: int
+    fuseki_dataset: str
+    fuseki_config: Path
+    public_gateway_bind: str | None
+    lifecycle_owner: str
+    runtime_version: str
+    release_version: str | None
+    semantic_revision: str
+    schema_version: int = SCHEMA_VERSION
+    installation_root: Path | None = None
+    environment_root: Path | None = None
+    python_executable: Path | None = None
+    mcp_executable: Path | None = None
+    instance_marker: Path | None = None
+    instance_state: str | None = None
+    plan_digest: str | None = None
+    artifact_set_digest: str | None = None
+    native_mcp_distribution: str | None = None
+    native_mcp_version: str | None = None
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "runtime_id", RuntimeId(self.runtime_id))
+        object.__setattr__(self, "environment_kind", EnvironmentKind(self.environment_kind))
+        object.__setattr__(self, "source_kind", SourceKind(self.source_kind))
+        object.__setattr__(self, "mcp_transport", McpTransport(self.mcp_transport))
+        object.__setattr__(self, "mcp_command", None if self.mcp_command is None else tuple(self.mcp_command))
+        object.__setattr__(self, "tool_versions", MappingProxyType(dict(self.tool_versions)))
+        home = CogniflowHome.at(self.home_root)
+        object.__setattr__(self, "home_root", home.root)
+        for field in ("runtime_root", "data_root", "fuseki_config"):
+            strict = _strict_path(getattr(self, field), field)
+            object.__setattr__(self, field, home.validate_path(strict, label=field))
+        object.__setattr__(self, "source_root", _strict_path(self.source_root, "source root").resolve(strict=False))
+        for field in ("installation_root", "environment_root", "python_executable", "mcp_executable", "instance_marker"):
+            value = getattr(self, field)
+            if value is not None:
+                object.__setattr__(self, field, _strict_path(value, field).resolve(strict=False))
+        self.validate()
+
+    def validate(self) -> None:
+        if isinstance(self.schema_version, bool) or self.schema_version != SCHEMA_VERSION:
+            raise ValueError(f"manifest schema version must be {SCHEMA_VERSION}")
+        paths = CogniflowHome.at(self.home_root).runtime(self.runtime_id)
+        if self.runtime_root != paths.runtime_root or self.data_root != paths.data or self.fuseki_config != paths.fuseki_config:
+            raise ValueError("manifest paths do not match the canonical runtime layout")
+        _loopback(self.fuseki_bind, "Fuseki bind")
+        if isinstance(self.fuseki_port, bool) or not isinstance(self.fuseki_port, int) or not 1 <= self.fuseki_port <= 65535:
+            raise ValueError("Fuseki port must be an integer from 1 to 65535")
+        for value, label in ((self.fuseki_dataset, "Fuseki dataset"), (self.lifecycle_owner, "lifecycle owner"),
+                             (self.runtime_version, "runtime version"), (self.semantic_revision, "semantic revision")):
+            _text(value, label)
+        if not _DATASET_NAME.fullmatch(self.fuseki_dataset):
+            raise ValueError("Fuseki dataset must be a safe path identifier")
+        if set(self.tool_versions) != {"fuseki", "java"} or any(not isinstance(v, str) or not v for v in self.tool_versions.values()):
+            raise ValueError("tool versions must contain exactly non-empty fuseki and java strings")
+        if self.public_gateway_bind is not None:
+            _loopback(self.public_gateway_bind, "public gateway bind")
+        if self.runtime_id.value != self.environment_kind.value:
+            raise ValueError("runtime id and environment kind must agree")
+        if self.runtime_id is RuntimeId.DEVELOPMENT:
+            if (self.source_kind is not SourceKind.WORKING_TREE or self.lifecycle_owner != "cf-runtime"
+                    or self.release_version is not None or self.mcp_transport is not McpTransport.STDIO
+                    or not self.mcp_command or any(not isinstance(v, str) or not v for v in self.mcp_command)):
+                raise ValueError("development requires a cf-runtime working tree stdio command and no release")
+            if not self.source_root.is_dir():
+                raise ValueError("development source must be an existing working tree")
+            if self.mcp_executable is not None:
+                raise ValueError("development cannot contain an installed MCP executable")
+        else:
+            if (self.source_kind is not SourceKind.RELEASE or self.lifecycle_owner != "cf-runtime"
+                    or not self.release_version or self.mcp_transport is not McpTransport.STDIO
+                    or self.mcp_command is None):
+                raise ValueError("production requires an explicitly provisioned installed stdio composition")
+            required = (self.installation_root, self.environment_root, self.python_executable,
+                        self.mcp_executable, self.instance_marker, self.plan_digest,
+                        self.artifact_set_digest, self.native_mcp_distribution, self.native_mcp_version)
+            if any(value is None for value in required) or self.instance_state != "ready":
+                raise ValueError("production instance binding is incomplete")
+            if len(self.mcp_command) != 1 or not _same_path(Path(self.mcp_command[0]), self.mcp_executable):
+                raise ValueError("production MCP command must name the installed executable")
+            _validate_installed_paths(self)
+
+    def to_toml(self) -> str:
+        def q(value: str) -> str:
+            return '"' + value.replace("\\", "\\\\").replace('"', '\\"').replace("\n", "\\n") + '"'
+        lines = ["[schema]", f"version = {self.schema_version}", "", "[runtime]", f"id = {q(self.runtime_id.value)}",
+                 f"kind = {q(self.environment_kind.value)}", "", "[paths]", f"home = {q(str(self.home_root))}",
+                 f"runtime = {q(str(self.runtime_root))}", f"data = {q(str(self.data_root))}", "", "[source]",
+                 f"kind = {q(self.source_kind.value)}", f"root = {q(str(self.source_root))}", "", "[tools]"]
+        lines.extend(f"{q(key)} = {q(self.tool_versions[key])}" for key in sorted(self.tool_versions))
+        lines.extend(["", "[mcp]", f"transport = {q(self.mcp_transport.value)}"])
+        if self.mcp_command is not None:
+            lines.append("command = [" + ", ".join(q(item) for item in self.mcp_command) + "]")
+        if self.mcp_executable is not None:
+            lines.append(f"executable = {q(str(self.mcp_executable))}")
+        lines.extend(["", "[fuseki]", f"bind = {q(self.fuseki_bind)}", f"port = {self.fuseki_port}",
+                      f"dataset = {q(self.fuseki_dataset)}", f"config = {q(str(self.fuseki_config))}", "", "[public_gateway]"])
+        if self.public_gateway_bind is not None:
+            lines.append(f"bind = {q(self.public_gateway_bind)}")
+        lines.extend(["", "[lifecycle]", f"owner = {q(self.lifecycle_owner)}", "", "[versions]",
+                      f"semantic = {q(self.semantic_revision)}", f"runtime = {q(self.runtime_version)}"])
+        if self.release_version is not None:
+            lines.append(f"release = {q(self.release_version)}")
+        if self.runtime_id is RuntimeId.PRODUCTION:
+            lines.extend(["", "[installation]", f"root = {q(str(self.installation_root))}",
+                          f"environment = {q(str(self.environment_root))}", f"python = {q(str(self.python_executable))}",
+                          "", "[instance]", f"marker = {q(str(self.instance_marker))}",
+                          f"state = {q(self.instance_state or '')}", f"plan_digest = {q(self.plan_digest or '')}",
+                          f"artifact_set_digest = {q(self.artifact_set_digest or '')}",
+                          f"native_mcp_distribution = {q(self.native_mcp_distribution or '')}",
+                          f"native_mcp_version = {q(self.native_mcp_version or '')}"])
+        return "\n".join(lines) + "\n"
+
+    @classmethod
+    def from_toml(cls, content: str | bytes) -> RuntimeManifest:
+        try:
+            raw = tomllib.loads(content.decode() if isinstance(content, bytes) else content)
+        except (tomllib.TOMLDecodeError, UnicodeDecodeError) as error:
+            raise ValueError(f"invalid runtime manifest TOML: {error}") from error
+        if not isinstance(raw, dict) or not _BASE_TOP_KEYS <= set(raw) or set(raw) - _BASE_TOP_KEYS - {"installation", "instance"}:
+            raise ValueError("manifest contains unknown top-level tables")
+        runtime_id = raw.get("runtime", {}).get("id") if isinstance(raw.get("runtime"), dict) else None
+        expected_top = _BASE_TOP_KEYS if runtime_id == "development" else _BASE_TOP_KEYS | {"installation", "instance"}
+        if set(raw) != expected_top:
+            raise ValueError(f"manifest tables must be exactly {sorted(expected_top)}")
+        for table, keys in _TABLE_KEYS.items():
+            if table not in raw:
+                continue
+            if not isinstance(raw[table], dict) or not set(raw[table]).issubset(keys):
+                raise ValueError(f"unexpected fields in [{table}]")
+        for table, keys in _REQUIRED.items():
+            if set(raw[table]) != keys:
+                raise ValueError(f"missing fields in [{table}]")
+        if set(raw["versions"]) not in ({"semantic", "runtime"}, {"semantic", "runtime", "release"}):
+            raise ValueError("invalid fields in [versions]")
+        transport = raw["mcp"].get("transport")
+        expected_mcp = {"transport", "command"} if transport == "stdio" else {"transport"}
+        if transport == "stdio" and "executable" in raw["mcp"]:
+            expected_mcp.add("executable")
+        if set(raw["mcp"]) != expected_mcp or not isinstance(raw["tools"], dict):
+            raise ValueError("invalid fields in [mcp] or [tools]")
+        if transport == "stdio" and (not isinstance(raw["mcp"].get("command"), list)
+                                      or not all(isinstance(item, str) and item for item in raw["mcp"]["command"])):
+            raise ValueError("MCP command must be a nonempty string array")
+        if raw["runtime"].get("id") == "development":
+            installation, instance = {}, {}
+        else:
+            installation, instance = raw["installation"], raw["instance"]
+            if set(installation) != {"root", "environment", "python"} or set(instance) != _TABLE_KEYS["instance"]:
+                raise ValueError("installed production fields are incomplete")
+        try:
+            return cls(raw["runtime"]["id"], raw["runtime"]["kind"], Path(raw["paths"]["home"]),
+                       Path(raw["paths"]["runtime"]), Path(raw["paths"]["data"]), raw["source"]["kind"],
+                       Path(raw["source"]["root"]), raw["tools"], transport,
+                       tuple(raw["mcp"]["command"]) if "command" in raw["mcp"] else None,
+                       raw["fuseki"]["bind"], raw["fuseki"]["port"], raw["fuseki"]["dataset"],
+                       Path(raw["fuseki"]["config"]), raw["public_gateway"].get("bind"), raw["lifecycle"]["owner"],
+                        raw["versions"]["runtime"], raw["versions"].get("release"), raw["versions"]["semantic"],
+                        raw["schema"]["version"],
+                        Path(installation["root"]) if installation else None,
+                        Path(installation["environment"]) if installation else None,
+                        Path(installation["python"]) if installation else None,
+                        Path(raw["mcp"]["executable"]) if "executable" in raw["mcp"] else None,
+                        Path(instance["marker"]) if instance else None,
+                        instance.get("state"), instance.get("plan_digest"),
+                        instance.get("artifact_set_digest"), instance.get("native_mcp_distribution"),
+                        instance.get("native_mcp_version"))
+        except (KeyError, TypeError, ValueError) as error:
+            raise ValueError(f"invalid runtime manifest: {error}") from error
+
+    @classmethod
+    def read(cls, path: str | Path) -> RuntimeManifest:
+        return cls.from_toml(Path(path).read_bytes())
+
+    def write(self, path: str | Path) -> None:
+        home = CogniflowHome.at(self.home_root)
+        destination = home.validate_path(path, label="manifest path")
+        if destination != home.runtime(self.runtime_id).manifest or not destination.parent.is_dir():
+            raise ValueError("manifest must use a prepared canonical runtime path")
+        if destination.is_symlink():
+            raise ValueError("manifest path must not be a symlink")
+        other_id = RuntimeId.PRODUCTION if self.runtime_id is RuntimeId.DEVELOPMENT else RuntimeId.DEVELOPMENT
+        other_path = home.runtime(other_id).manifest
+        if other_path.is_file():
+            other = RuntimeManifest.read(other_path)
+            development, production = ((self, other) if self.runtime_id is RuntimeId.DEVELOPMENT else (other, self))
+            validate_manifest_pair(development, production)
+        if destination.is_file() and self.runtime_id is RuntimeId.PRODUCTION:
+            if destination.read_bytes() != self.to_toml().encode("utf-8"):
+                raise ValueError("production manifest already contains a conflicting composition")
+            return
+        _atomic_text(destination, self.to_toml())
+
+
+def development_manifest(home: CogniflowHome, *, source_root: str | Path, runtime_version: str,
+                         semantic_revision: str, tool_versions: Mapping[str, str],
+                         mcp_command: tuple[str, ...] = DEFAULT_DEVELOPMENT_MCP_COMMAND,
+                         fuseki_dataset: str = "cogniflow", public_gateway_bind: str | None = "127.0.0.1") -> RuntimeManifest:
+    paths = home.runtime(RuntimeId.DEVELOPMENT)
+    return RuntimeManifest(RuntimeId.DEVELOPMENT, EnvironmentKind.DEVELOPMENT, home.root, paths.runtime_root, paths.data,
+                           SourceKind.WORKING_TREE, Path(source_root), tool_versions, McpTransport.STDIO, mcp_command,
+                           "127.0.0.1", DEFAULT_DEVELOPMENT_FUSEKI_PORT, fuseki_dataset, paths.fuseki_config,
+                           public_gateway_bind, "cf-runtime", runtime_version, None, semantic_revision)
+
+
+def production_manifest(home: CogniflowHome, *, release_version: str, runtime_version: str,
+                         semantic_revision: str, tool_versions: Mapping[str, str], installation_root: str | Path,
+                         environment_root: str | Path, python_executable: str | Path,
+                         mcp_executable: str | Path, instance_marker: str | Path,
+                         plan_digest: str, artifact_set_digest: str, native_mcp_distribution: str,
+                         native_mcp_version: str, lifecycle_owner: str = "cf-runtime",
+                         fuseki_dataset: str = "cogniflow", public_gateway_bind: str | None = "127.0.0.1") -> RuntimeManifest:
+    paths = home.runtime(RuntimeId.PRODUCTION)
+    return RuntimeManifest(RuntimeId.PRODUCTION, EnvironmentKind.PRODUCTION, home.root, paths.runtime_root, paths.data,
+                           SourceKind.RELEASE, Path(installation_root), tool_versions, McpTransport.STDIO,
+                           (str(mcp_executable),),
+                           "127.0.0.1", DEFAULT_PRODUCTION_FUSEKI_PORT, fuseki_dataset, paths.fuseki_config,
+                           public_gateway_bind, lifecycle_owner, runtime_version, release_version, semantic_revision,
+                           installation_root=installation_root, environment_root=environment_root,
+                           python_executable=python_executable, mcp_executable=mcp_executable,
+                           instance_marker=instance_marker, instance_state="ready", plan_digest=plan_digest,
+                           artifact_set_digest=artifact_set_digest, native_mcp_distribution=native_mcp_distribution,
+                           native_mcp_version=native_mcp_version)
+
+
+def validate_manifest_pair(development: RuntimeManifest, production: RuntimeManifest) -> None:
+    development.validate()
+    production.validate()
+    by_id = {development.runtime_id: development, production.runtime_id: production}
+    if set(by_id) != {RuntimeId.DEVELOPMENT, RuntimeId.PRODUCTION}:
+        raise ValueError("manifest pair must contain development and production")
+    if development.fuseki_port == production.fuseki_port:
+        raise ValueError("development and production cannot use duplicate ports")