cf-runtime 0.1.8__py3-none-any.whl

cf_runtime/__init__.py

@@ -0,0 +1,74 @@
+"""Local Cogniflow runtime bootstrap and lifecycle provider."""
+
+from pathlib import Path
+
+from .domain import EnvironmentKind, McpTransport, RuntimeId, SourceKind
+from .manifest import (
+    DEFAULT_DEVELOPMENT_FUSEKI_PORT,
+    DEFAULT_DEVELOPMENT_MCP_COMMAND,
+    DEFAULT_PRODUCTION_FUSEKI_PORT,
+    DEFAULT_RUNTIME_VERSION,
+    DEFAULT_TOOL_VERSIONS,
+    RuntimeManifest,
+    development_manifest,
+    production_manifest,
+    validate_manifest_pair,
+)
+from .paths import CogniflowHome, RuntimePaths
+from .managed_tools import ManagedTools, ManagedToolsError, catalog, normalized_platform
+from .lifecycle import ProductionRuntime
+from .target import (
+    RuntimeIdentity,
+    RuntimeTarget,
+    resolve_runtime_target,
+    verify_runtime_target,
+)
+
+PACKAGE_DISTRIBUTION = "cf-runtime"
+PYTHON_PACKAGE = "cf_runtime"
+PACKAGE_VERSION = "0.1.8"
+
+
+def package_root() -> Path:
+    return Path(__file__).resolve().parent
+
+
+def semantics_dir() -> Path:
+    return package_root() / "semantics"
+
+
+def semantic_files() -> tuple[Path, ...]:
+    return (semantics_dir() / "package.trig",)
+
+__all__ = [
+    "CogniflowHome",
+    "ManagedTools",
+    "ManagedToolsError",
+    "ProductionRuntime",
+    "DEFAULT_DEVELOPMENT_FUSEKI_PORT",
+    "DEFAULT_DEVELOPMENT_MCP_COMMAND",
+    "DEFAULT_PRODUCTION_FUSEKI_PORT",
+    "DEFAULT_RUNTIME_VERSION",
+    "DEFAULT_TOOL_VERSIONS",
+    "EnvironmentKind",
+    "McpTransport",
+    "PACKAGE_DISTRIBUTION",
+    "PACKAGE_VERSION",
+    "PYTHON_PACKAGE",
+    "RuntimeId",
+    "RuntimeIdentity",
+    "RuntimeManifest",
+    "RuntimePaths",
+    "RuntimeTarget",
+    "SourceKind",
+    "development_manifest",
+    "production_manifest",
+    "package_root",
+    "resolve_runtime_target",
+    "semantic_files",
+    "semantics_dir",
+    "validate_manifest_pair",
+    "catalog",
+    "normalized_platform",
+    "verify_runtime_target",
+]

cf_runtime/bootstrap.py

@@ -0,0 +1,376 @@
+"""Versioned JSON-lines bootstrap provider executable."""
+
+from __future__ import annotations
+
+import base64
+import json
+import re
+from pathlib import Path
+import sys
+from typing import Callable
+
+from .domain import RuntimeId
+from .lifecycle import DevelopmentRuntime, ProductionRuntime
+from .locking import LifecycleLockedError
+from .managed_tools import MANAGED_REQUEST_SCHEMA, ManagedTools, ManagedToolsError
+from .paths import CogniflowHome
+from .target import resolve_runtime_target
+from .manifest import RuntimeManifest, production_manifest
+from dataclasses import replace
+from .semantics import recover_stopped as recover_stopped_semantics, register as register_semantics, restore as restore_semantics, status as status_semantics, transition as transition_semantics, uninstall as uninstall_semantics
+from .teardown import attest as attest_teardown, cleanup as cleanup_teardown, finalize as finalize_teardown, plan as plan_teardown, prepare as prepare_teardown, recover as recover_teardown, stop as stop_teardown
+
+JSONRPC = "2.0"
+PROTOCOL = "cf.runtime.bootstrap.v1"
+_REQUEST_FIELDS = {"jsonrpc", "protocol", "id", "method", "params"}
+
+
+class ProtocolError(Exception):
+    def __init__(self, code: str, message: str) -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+
+
+def rebind_production_composition(home: CogniflowHome, snapshot: bytes, plan_digest: str, artifact_set_digest: str) -> None:
+    runtime = home.runtime(RuntimeId.PRODUCTION)
+    current = runtime.manifest.read_bytes()
+    text = snapshot.decode("utf-8")
+    rebound_text = re.sub(r'(?m)^plan_digest = "[^"]*"$', f'plan_digest = "{plan_digest}"', text, count=1)
+    rebound_text = re.sub(r'(?m)^artifact_set_digest = "[^"]*"$', f'artifact_set_digest = "{artifact_set_digest}"', rebound_text, count=1)
+    if rebound_text == text or rebound_text.count(plan_digest) != 1 or rebound_text.count(artifact_set_digest) != 1:
+        raise ValueError("production runtime manifest authority fields are invalid")
+    expected_b = RuntimeManifest.from_toml(rebound_text)
+    expected_b_bytes = expected_b.to_toml().encode("utf-8")
+    if current != snapshot and current != expected_b_bytes:
+        raise ValueError("production runtime manifest is mixed or foreign")
+    if current == expected_b_bytes:
+        return
+    temporary = runtime.manifest.with_suffix(".transition.tmp")
+    temporary.write_bytes(expected_b_bytes)
+    temporary.replace(runtime.manifest)
+
+
+def _request_id(value: object) -> bool:
+    return (isinstance(value, int) and not isinstance(value, bool)) or (isinstance(value, str) and bool(value))
+
+
+def _home(params: dict[str, object]) -> CogniflowHome:
+    value = params.get("cogniflow_home")
+    if value is None:
+        return CogniflowHome.default()
+    if not isinstance(value, str) or not value or "://" in value:
+        raise ProtocolError("INVALID_REQUEST", "cogniflow_home must be a local path string")
+    return CogniflowHome.at(value)
+
+
+def _fields(params: object, *, required: set[str], optional: set[str]) -> dict[str, object]:
+    if not isinstance(params, dict) or any(not isinstance(key, str) for key in params):
+        raise ProtocolError("INVALID_REQUEST", "params must be an object with string fields")
+    if set(params) - required - optional or required - set(params):
+        raise ProtocolError("INVALID_REQUEST", "params fields do not match the operation schema")
+    return params
+
+
+def _path(params: dict[str, object], name: str) -> Path:
+    value = params[name]
+    if not isinstance(value, str) or not value or "://" in value:
+        raise ProtocolError("INVALID_REQUEST", f"{name} must be a local path string")
+    return Path(value)
+
+
+def _timeout(params: dict[str, object], name: str, default: float, *, allow_zero: bool = False) -> float:
+    value = params.get(name, default)
+    minimum = 0 if allow_zero else 0.001
+    if isinstance(value, bool) or not isinstance(value, (int, float)) or not minimum <= value <= 300:
+        raise ProtocolError("INVALID_REQUEST", f"{name} must be a number between {minimum} and 300")
+    return float(value)
+
+
+def _manager(params: dict[str, object]) -> DevelopmentRuntime:
+    return DevelopmentRuntime(_home(params), lock_timeout=_timeout(params, "lock_timeout_seconds", 0.0, allow_zero=True))
+
+
+def _resolve(params: object) -> dict[str, object]:
+    values = _fields(params, required={"runtime_id"}, optional={"cogniflow_home", "required_runtime_version", "required_semantic_revision"})
+    runtime_id = values["runtime_id"]
+    if runtime_id == "production":
+        try:
+            target = resolve_runtime_target(_home(values), RuntimeId.PRODUCTION)
+        except FileNotFoundError as error:
+            raise ProtocolError("PRODUCTION_RUNTIME_NOT_PROVISIONED", "production runtime has not been explicitly provisioned") from error
+        except ValueError as error:
+            raise ProtocolError("PRODUCTION_RUNTIME_INVALID", str(error)) from error
+        return target.payload()
+    if runtime_id != "development":
+        raise ProtocolError("INVALID_REQUEST", "runtime_id must be development or production")
+    for key in ("required_runtime_version", "required_semantic_revision"):
+        if key in values and (not isinstance(values[key], str) or not values[key]):
+            raise ProtocolError("INVALID_REQUEST", f"{key} must be a nonempty string")
+    target = resolve_runtime_target(_home(values), RuntimeId.DEVELOPMENT,
+                                    required_runtime_version=values.get("required_runtime_version"),
+                                    required_semantic_revision=values.get("required_semantic_revision"))
+    return target.payload()
+
+
+def _production_preflight(params: object) -> dict[str, object]:
+    required = {"runtime_version", "release_version", "semantic_revision", "tool_versions",
+                "installation_root", "environment_root", "python_executable", "mcp_executable",
+                "instance_marker", "plan_digest", "artifact_set_digest", "native_mcp_distribution",
+                "native_mcp_version"}
+    values = _fields(params, required=required, optional={"cogniflow_home", "lock_timeout_seconds"})
+    tools = values["tool_versions"]
+    if not isinstance(tools, dict) or set(tools) != {"java", "fuseki"} or any(not isinstance(value, str) or not value for value in tools.values()):
+        raise ProtocolError("INVALID_REQUEST", "tool_versions must contain exactly java and fuseki strings")
+    for key in required - {"tool_versions"}:
+        if not isinstance(values[key], str) or not values[key]:
+            raise ProtocolError("INVALID_REQUEST", f"{key} must be a nonempty string")
+    home = _home(values)
+    from .locking import LifecycleLock
+    paths = home.runtime(RuntimeId.PRODUCTION)
+    with LifecycleLock(paths.lifecycle_lock, _timeout(values, "lock_timeout_seconds", 0.0, allow_zero=True)):
+        manifest = production_manifest(home, release_version=values["release_version"],
+            runtime_version=values["runtime_version"], semantic_revision=values["semantic_revision"],
+            tool_versions=tools, installation_root=_path(values, "installation_root"),
+            environment_root=_path(values, "environment_root"), python_executable=_path(values, "python_executable"),
+            mcp_executable=_path(values, "mcp_executable"), instance_marker=_path(values, "instance_marker"),
+            plan_digest=values["plan_digest"], artifact_set_digest=values["artifact_set_digest"],
+            native_mcp_distribution=values["native_mcp_distribution"], native_mcp_version=values["native_mcp_version"])
+        paths.ensure_directories()
+        content = manifest.to_toml().encode("utf-8")
+        if paths.manifest.exists():
+            if paths.manifest.read_bytes() != content:
+                raise ValueError("production manifest already contains a conflicting composition")
+        else:
+            manifest.write(paths.manifest)
+    return {"runtime_id": "production", "status": "preflight", "manifest": str(paths.manifest),
+            "semantic_revision": manifest.semantic_revision}
+
+
+def _production_start(params: object) -> dict[str, object]:
+    values = _fields(params, required=set(), optional={"cogniflow_home", "lock_timeout_seconds", "timeout_seconds"})
+    return ProductionRuntime(_home(values), lock_timeout=_timeout(values, "lock_timeout_seconds", 0.0, allow_zero=True)).start(
+        timeout=_timeout(values, "timeout_seconds", 30.0))
+
+
+def _production_status(params: object) -> dict[str, object]:
+    values = _fields(params, required=set(), optional={"cogniflow_home", "lock_timeout_seconds"})
+    return ProductionRuntime(_home(values), lock_timeout=_timeout(values, "lock_timeout_seconds", 0.0, allow_zero=True)).status()
+
+
+def _production_stop(params: object) -> dict[str, object]:
+    values = _fields(params, required=set(), optional={"cogniflow_home", "lock_timeout_seconds", "timeout_seconds"})
+    return ProductionRuntime(_home(values), lock_timeout=_timeout(values, "lock_timeout_seconds", 0.0, allow_zero=True)).stop(
+        timeout=_timeout(values, "timeout_seconds", 5.0))
+
+
+def _production_rebind(params: object) -> dict[str, object]:
+    values = _fields(params, required={"cogniflow_home", "snapshot_base64", "plan_digest", "artifact_set_digest"}, optional=set())
+    snapshot_value = values["snapshot_base64"]
+    if not isinstance(snapshot_value, str) or not snapshot_value:
+        raise ProtocolError("INVALID_REQUEST", "snapshot_base64 must be a nonempty canonical base64 string")
+    try:
+        snapshot = base64.b64decode(snapshot_value, validate=True)
+    except (ValueError, TypeError) as error:
+        raise ProtocolError("INVALID_REQUEST", "snapshot_base64 must be valid base64") from error
+    if base64.b64encode(snapshot).decode("ascii") != snapshot_value:
+        raise ProtocolError("INVALID_REQUEST", "snapshot_base64 must be canonical base64")
+    for name in ("plan_digest", "artifact_set_digest"):
+        value = values[name]
+        if not isinstance(value, str) or not re.fullmatch(r"sha256:[0-9a-f]{64}", value):
+            raise ProtocolError("INVALID_REQUEST", f"{name} must be a sha256 digest")
+    rebind_production_composition(_home(values), snapshot, values["plan_digest"], values["artifact_set_digest"])
+    return {"runtime_id": "production", "status": "rebound"}
+
+
+def _production_semantics_register(params: object) -> dict[str, object]:
+    values = _fields(params, required={"documents"}, optional={"cogniflow_home", "lock_timeout_seconds"})
+    return register_semantics(_home(values), values["documents"])
+
+
+def _production_semantics_restore(params: object) -> dict[str, object]:
+    values = _fields(params, required={"receipt"}, optional={"cogniflow_home", "lock_timeout_seconds"})
+    return restore_semantics(_home(values), values["receipt"])
+
+
+def _production_semantics_recover_stopped(params: object) -> dict[str, object]:
+    values = _fields(params, required={"receipt"}, optional={"cogniflow_home", "timeout_seconds"})
+    return recover_stopped_semantics(_home(values), values["receipt"], timeout=_timeout(values, "timeout_seconds", 30.0))
+
+
+def _production_semantics_transition(params: object) -> dict[str, object]:
+    values = _fields(params, required={"before", "after"}, optional={"cogniflow_home", "lock_timeout_seconds"})
+    return transition_semantics(_home(values), values["before"], values["after"])
+
+
+def _production_semantics_uninstall(params: object) -> dict[str, object]:
+    values = _fields(params, required={"documents"}, optional={"cogniflow_home", "lock_timeout_seconds"})
+    return uninstall_semantics(_home(values), values["documents"])
+
+
+def _production_semantics_status(params: object) -> dict[str, object]:
+    values = _fields(params, required={"documents"}, optional={"cogniflow_home", "lock_timeout_seconds"})
+    return status_semantics(_home(values), values["documents"])
+
+
+def _production_teardown_plan(params: object) -> dict[str, object]:
+    values = _fields(params, required=set(), optional={"cogniflow_home"})
+    return plan_teardown(_home(values))
+
+
+def _production_teardown_prepare(params: object) -> dict[str, object]:
+    values = _fields(params, required={"transaction_id", "nonce", "authority", "preview_digest", "documents"}, optional={"cogniflow_home"})
+    return prepare_teardown(_home(values), transaction_id=values["transaction_id"], nonce=values["nonce"], authority=values["authority"], preview_digest=values["preview_digest"], documents=values["documents"])
+
+
+def _production_teardown_attest(params: object) -> dict[str, object]:
+    values = _fields(params, required={"transaction"}, optional={"cogniflow_home"})
+    return attest_teardown(_home(values), values["transaction"])
+
+
+def _production_teardown_stop(params: object) -> dict[str, object]:
+    values = _fields(params, required={"transaction"}, optional={"cogniflow_home", "timeout_seconds"})
+    return stop_teardown(_home(values), values["transaction"], timeout=_timeout(values, "timeout_seconds", 30.0))
+
+
+def _production_teardown_cleanup(params: object) -> dict[str, object]:
+    values = _fields(params, required={"transaction"}, optional={"cogniflow_home"})
+    return cleanup_teardown(_home(values), values["transaction"])
+
+
+def _production_teardown_finalize(params: object) -> dict[str, object]:
+    values = _fields(params, required={"transaction"}, optional={"cogniflow_home"})
+    return finalize_teardown(_home(values), values["transaction"])
+
+
+def _production_teardown_recover(params: object) -> dict[str, object]:
+    values = _fields(params, required={"transaction"}, optional={"cogniflow_home", "timeout_seconds"})
+    return recover_teardown(_home(values), values["transaction"], timeout=_timeout(values, "timeout_seconds", 30.0))
+
+
+def _prepare(params: object) -> dict[str, object]:
+    values = _fields(params, required={"source_root", "semantic_seed"},
+                     optional={"cogniflow_home", "lock_timeout_seconds"})
+    return _manager(values).prepare(_path(values, "source_root"), _path(values, "semantic_seed"))
+
+
+def _start(params: object) -> dict[str, object]:
+    values = _fields(params, required={"source_root", "semantic_seed"},
+                     optional={"cogniflow_home", "lock_timeout_seconds", "timeout_seconds"})
+    return _manager(values).start(_path(values, "source_root"), _path(values, "semantic_seed"),
+                                  timeout=_timeout(values, "timeout_seconds", 30.0))
+
+
+def _status(params: object) -> dict[str, object]:
+    values = _fields(params, required=set(), optional={"cogniflow_home", "lock_timeout_seconds"})
+    return _manager(values).status()
+
+
+def _stop(params: object) -> dict[str, object]:
+    values = _fields(params, required=set(), optional={"cogniflow_home", "lock_timeout_seconds", "timeout_seconds"})
+    return _manager(values).stop(timeout=_timeout(values, "timeout_seconds", 5.0))
+
+
+def _managed_tools(params: object) -> dict[str, object]:
+    values = _fields(params, required={"schema", "tools"}, optional={"cogniflow_home", "lock_timeout_seconds"})
+    if values["schema"] != MANAGED_REQUEST_SCHEMA:
+        raise ProtocolError("SCHEMA_UNSUPPORTED", "unsupported managed-tools request schema")
+    tools = values["tools"]
+    if not isinstance(tools, list) or len(tools) != 2:
+        raise ProtocolError("INVALID_REQUEST", "tools must contain exactly java and fuseki")
+    versions: dict[str, str] = {}
+    for item in tools:
+        if not isinstance(item, dict) or set(item) != {"name", "version"} or item.get("name") in versions:
+            raise ProtocolError("INVALID_REQUEST", "tool requests are strict name/version objects")
+        if item["name"] not in {"java", "fuseki"} or not isinstance(item["version"], str) or not item["version"]:
+            raise ProtocolError("INVALID_REQUEST", "invalid managed tool request")
+        versions[item["name"]] = item["version"]
+    if set(versions) != {"java", "fuseki"}:
+        raise ProtocolError("INVALID_REQUEST", "java and fuseki are both required")
+    try:
+        return ManagedTools(_home(values), lock_timeout=_timeout(values, "lock_timeout_seconds", 0.0, allow_zero=True)).provision(versions["java"], versions["fuseki"])
+    except LifecycleLockedError as error:
+        raise ProtocolError("MANAGED_TOOLS_LOCKED", "managed-tool provisioning is locked") from error
+    except ManagedToolsError as error:
+        raise ProtocolError(error.code, str(error)) from error
+
+
+_OPERATIONS: dict[str, Callable[[object], dict[str, object]]] = {
+    "runtime/resolve-target": _resolve,
+    "production/preflight": _production_preflight,
+    "production/start": _production_start,
+    "production/status": _production_status,
+    "production/stop": _production_stop,
+    "production/composition/rebind": _production_rebind,
+    "production/semantics/register": _production_semantics_register,
+    "production/semantics/restore": _production_semantics_restore,
+    "production/semantics/recover-stopped": _production_semantics_recover_stopped,
+    "production/semantics/transition": _production_semantics_transition,
+    "production/semantics/status": _production_semantics_status,
+    "production/semantics/uninstall": _production_semantics_uninstall,
+    "production/teardown/plan": _production_teardown_plan,
+    "production/teardown/prepare": _production_teardown_prepare,
+    "production/teardown/attest": _production_teardown_attest,
+    "production/teardown/stop": _production_teardown_stop,
+    "production/teardown/cleanup": _production_teardown_cleanup,
+    "production/teardown/finalize": _production_teardown_finalize,
+    "production/teardown/recover": _production_teardown_recover,
+    "development/prepare": _prepare,
+    "development/start": _start,
+    "development/status": _status,
+    "development/stop": _stop,
+    "managed-tools/provision": _managed_tools,
+}
+
+
+def handle(payload: object) -> dict[str, object]:
+    request_id: object = None
+    method = "unknown"
+    try:
+        if not isinstance(payload, dict) or set(payload) != _REQUEST_FIELDS:
+            raise ProtocolError("INVALID_REQUEST", "request fields do not match the protocol")
+        candidate_id = payload.get("id")
+        if not _request_id(candidate_id) or payload.get("jsonrpc") != JSONRPC:
+            raise ProtocolError("INVALID_REQUEST", "invalid jsonrpc or request id")
+        request_id = candidate_id
+        if payload.get("protocol") != PROTOCOL:
+            raise ProtocolError("PROTOCOL_VERSION_UNSUPPORTED", "unsupported bootstrap protocol version")
+        method = payload.get("method")
+        if not isinstance(method, str) or not method:
+            raise ProtocolError("INVALID_REQUEST", "method must be a nonempty string")
+        operation = _OPERATIONS.get(method)
+        if operation is None:
+            raise ProtocolError("UNKNOWN_OPERATION", "unknown bootstrap operation")
+        result = operation(payload.get("params"))
+        return {"jsonrpc": JSONRPC, "protocol": PROTOCOL, "id": request_id, "result": result}
+    except LifecycleLockedError:
+        error = ProtocolError("DEVELOPMENT_LIFECYCLE_LOCKED", "development lifecycle is locked")
+    except ProtocolError as caught:
+        error = caught
+    except (ValueError, TypeError, FileNotFoundError) as caught:
+        error = ProtocolError("INVALID_REQUEST", str(caught))
+    except Exception as caught:
+        # Keep provider failures useful without returning URLs, environments, or
+        # an unbounded traceback through the JSON protocol.
+        message = f"operation={method} exception={type(caught).__name__}: {caught}"
+        error = ProtocolError("INTERNAL_ERROR", message[:1024])
+    return {"jsonrpc": JSONRPC, "protocol": PROTOCOL, "id": request_id,
+            "error": {"code": error.code, "message": error.message}}
+
+
+def main() -> int:
+    for line in sys.stdin:
+        try:
+            payload = json.loads(line)
+        except json.JSONDecodeError:
+            response = {"jsonrpc": JSONRPC, "protocol": PROTOCOL, "id": None,
+                        "error": {"code": "INVALID_REQUEST", "message": "request must be valid JSON"}}
+        else:
+            response = handle(payload)
+        sys.stdout.write(json.dumps(response, sort_keys=True, separators=(",", ":")) + "\n")
+        sys.stdout.flush()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

cf_runtime/domain.py

@@ -0,0 +1,25 @@
+"""Closed vocabulary used by the runtime domain."""
+
+from enum import Enum
+
+
+class RuntimeId(str, Enum):
+    DEVELOPMENT = "development"
+    PRODUCTION = "production"
+
+
+class EnvironmentKind(Enum):
+    """Deployment semantics, intentionally distinct from runtime identity."""
+
+    DEVELOPMENT = "development"
+    PRODUCTION = "production"
+
+
+class SourceKind(str, Enum):
+    WORKING_TREE = "working-tree"
+    RELEASE = "release"
+
+
+class McpTransport(str, Enum):
+    STDIO = "stdio"
+    UNAVAILABLE = "unavailable"

cf_runtime/installed_seed.py

@@ -0,0 +1,57 @@
+"""Build the production semantic seed from installed entry points only."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import importlib.metadata
+import os
+from pathlib import Path
+
+
+def build(output: Path) -> str:
+    root = Path(sys_prefix := os.path.abspath(os.sys.prefix))
+    records: list[tuple[str, str, Path]] = []
+    entries = importlib.metadata.entry_points().select(group="cogniflow.semantic_sources")
+    for entry in entries:
+        distribution = (entry.dist.metadata.get("Name") if entry.dist else "") or ""
+        value = entry.load()()
+        if not isinstance(value, (tuple, list)) or any(not isinstance(item, Path) for item in value):
+            raise ValueError(f"semantic source {entry.name} returned a non-Path sequence")
+        for path in value:
+            resolved = path.resolve(strict=True)
+            if not resolved.is_file() or resolved.is_symlink():
+                raise ValueError(f"semantic source is not a regular file: {path}")
+            try:
+                resolved.relative_to(root)
+            except ValueError as error:
+                raise ValueError(f"semantic source is outside the target environment: {path}") from error
+            records.append((distribution.casefold(), entry.name.casefold(), resolved))
+    records.sort(key=lambda item: (item[0], item[1], item[2].as_posix().casefold()))
+    chunks: list[bytes] = []
+    seen: set[Path] = set()
+    for distribution, name, path in records:
+        if path in seen:
+            raise ValueError(f"duplicate semantic source: {path}")
+        seen.add(path)
+        chunks.append(f"# source: {distribution}/{name}/{path.name}\n".encode("utf-8"))
+        data = path.read_bytes()
+        chunks.append(data.rstrip(b"\r\n") + b"\n")
+    data = b"".join(chunks)
+    output.parent.mkdir(parents=True, exist_ok=True)
+    temporary = output.with_name(f".{output.name}.tmp")
+    temporary.write_bytes(data)
+    os.replace(temporary, output)
+    return hashlib.sha256(data).hexdigest()
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--output", required=True)
+    args = parser.parse_args()
+    print(build(Path(args.output)))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())