modekeeper 0.1.1__tar.gz

modekeeper-0.1.1/LICENSE

@@ -0,0 +1,6 @@
+ModeKeeper — Proprietary License
+
+Copyright (c) 2026.
+
+All rights reserved. Unauthorized copying, modification, distribution, or use of this software,
+via any medium, is strictly prohibited without prior written permission.

modekeeper-0.1.1/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: modekeeper
+Version: 0.1.1
+Summary: ModeKeeper: self-serve observability and safe closed-loop tuning
+Author: ModeKeeper
+License-Expression: LicenseRef-Proprietary
+Keywords: mlops,observability,autotuning,safety
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4; extra == "dev"
+Requires-Dist: ruff>=0.4.8; extra == "dev"
+Dynamic: license-file
+
+# ModeKeeper
+<!-- modekeeper:product-intro:start -->
+
+## Для кого и зачем
+
+**ModeKeeper** — инструмент для платформенных команд (**SRE / MLOps / FinOps**), которые запускают обучение/инференс в **Kubernetes** и хотят **снижать стоимость и нестабильность** без риска и без “ручного тюнинга”.
+
+Что делает (в двух словах):
+- **наблюдает** метрики/состояние ворклоада и собирает контекст;
+- строит **план изменений** (**plan-only**, ничего не применяет);
+- умеет **проверить применимость** плана (**verify**, тоже без изменений);
+- в **платном режиме** может **применить** план (**apply**) внутри ModeKeeper — только при активной лицензии и после успешного verify.
+
+Режимы:
+- **Free:** observe + closed-loop dry-run + k8s render/verify (**ничего не меняет**)
+- **Paid:** one-shot `mk closed-loop run --apply` под `MODEKEEPER_PAID=1`; детали — `docs/WORKFLOW.md`.
+
+См. подробное продуктовое описание: `docs/product.md`.
+См. технический snapshot для продолжения: `docs/SNAPSHOT.md`.
+См. workflow (plan-only + verify + paid apply skeleton): `docs/WORKFLOW.md`.
+
+<!-- modekeeper:product-intro:end -->
+
+
+ModeKeeper — self-serve слой контроля для ML-систем. Сначала работает в режиме **OBSERVE_ONLY** (бесплатная неделя): собирает телеметрию и формирует отчет «теряете ли вы деньги». Затем, по желанию, включается режим **CLOSED_LOOP** для безопасного автотюнинга с guardrails и откатами.
+
+## Возможности
+- Два режима: `OBSERVE_ONLY` и `CLOSED_LOOP`.
+- Модульная архитектура: core, telemetry, actuators, policy, safety, adapters.
+- Explain-log везде: каждое решение, ограничение и действие фиксируется.
+- Локальные демо-сценарии без внешних сервисов.
+
+## Установка
+```bash
+python -m venv .venv
+. .venv/bin/activate
+pip install -e .
+```
+
+## Быстрый старт
+```bash
+mk observe --duration 250ms --out report/_observe_quick
+mk demo run --scenario drift
+mk closed-loop run --scenario drift --dry-run --out report/_golden_dryrun
+```
+Canonical paid e2e (kind) + scripts: `docs/WORKFLOW.md`.
+
+## Quickstart
+Observe-only quickstart + RBAC verify-only replay:
+`docs/QUICKSTART.md`
+
+## E2E (kind)
+Canonical workflow: `docs/WORKFLOW.md` (paid path is one-shot `closed-loop run --apply`).
+Continuation snapshot: `docs/SNAPSHOT.md`.
+
+Canonical scripts:
+- `./scripts/e2e-smoke-kind.sh` (safe: kill switch blocks apply)
+- `./scripts/e2e-apply-kind.sh` (REAL kubectl patches)
+
+Warning: `./scripts/e2e-apply-kind.sh` performs real `kubectl` patches in the kind cluster.
+
+Observe параметры:
+- `--source` synthetic|file (default: synthetic)
+- `--path` обязателен для `--source file`
+- `--duration` принимает `1.5s`, `250ms`, `10m`; без суффикса = секунды
+- формат входа: `jsonl`/`csv` с полями `ts`, `step_time_ms`, `loss` (optional)
+
+## Демо
+```bash
+mk demo run --scenario straggler
+mk demo run --scenario burst
+```
+
+Выходные данные (контракт v0):
+- `report/` содержит JSON-отчеты и `explain.jsonl` (JSONL, `ensure_ascii=False`).
+- `observe_latest.json`, `demo_latest.json`, `closed_loop_latest.json` — копии последних отчетов.
+- Подробности k8s утилит/полей — см. `docs/WORKFLOW.md` и `docs/SNAPSHOT.md`.
+- Все отчеты имеют поля верхнего уровня: `schema_version`, `started_at`, `finished_at`, `duration_s`, `out_dir`.
+- В `OBSERVE_ONLY` добавляется `summary`:
+  - `money_leak_risk` (low|medium|high)
+  - `top_symptoms`
+  - `recommendations`
+- В `CLOSED_LOOP` дополнительно создаётся `summary.md` (короткий человекочитаемый итог прогона).
+- В `CLOSED_LOOP` также пишутся plan-only артефакты: `k8s_plan.json` и `k8s_plan.kubectl.sh` (в dry-run kubectl **не выполняется**).
+- В `CLOSED_LOOP` добавляются поля:
+  - `decision_summary` (RU)
+  - `proposed` (предлагаемые действия)
+  - `applied` (результаты применения/блокировки)
+  - `status` (например, `"ok"`)
+  - `kill_switch_active` (true/false)
+  - `blocked_reasons` (агрегация причин блокировок)
+  - `applied_reasons` (агрегация причин применений)
+  - `k8s_plan_path` (путь к `k8s_plan.json`)
+  - `k8s_plan_items` (кол-во items в плане)
+  - `k8s_kubectl_plan_path` (путь к `k8s_plan.kubectl.sh`)
+  - `k8s_namespace` (целевой namespace для скрипта/плана)
+  - `k8s_deployment` (целевой deployment для скрипта/плана)
+
+## Примечания
+- `closed-loop` по умолчанию работает в dry-run; для paid-apply используйте one-shot `closed-loop run --apply` (см. `docs/WORKFLOW.md`).
+- В dry-run `closed-loop` **не выполняет** kubectl: он только генерирует `k8s_plan.kubectl.sh`.
+- Для принудительной блокировки `--apply` используйте `MODEKEEPER_KILL_SWITCH=1` (в отчёте `blocked_reasons` будет `kill_switch`).
+- Все safety-ограничения локальные, настраиваемые и аудируемые.

modekeeper-0.1.1/README.md

@@ -0,0 +1,103 @@
+# ModeKeeper
+<!-- modekeeper:product-intro:start -->
+
+## Для кого и зачем
+
+**ModeKeeper** — инструмент для платформенных команд (**SRE / MLOps / FinOps**), которые запускают обучение/инференс в **Kubernetes** и хотят **снижать стоимость и нестабильность** без риска и без “ручного тюнинга”.
+
+Что делает (в двух словах):
+- **наблюдает** метрики/состояние ворклоада и собирает контекст;
+- строит **план изменений** (**plan-only**, ничего не применяет);
+- умеет **проверить применимость** плана (**verify**, тоже без изменений);
+- в **платном режиме** может **применить** план (**apply**) внутри ModeKeeper — только при активной лицензии и после успешного verify.
+
+Режимы:
+- **Free:** observe + closed-loop dry-run + k8s render/verify (**ничего не меняет**)
+- **Paid:** one-shot `mk closed-loop run --apply` под `MODEKEEPER_PAID=1`; детали — `docs/WORKFLOW.md`.
+
+См. подробное продуктовое описание: `docs/product.md`.
+См. технический snapshot для продолжения: `docs/SNAPSHOT.md`.
+См. workflow (plan-only + verify + paid apply skeleton): `docs/WORKFLOW.md`.
+
+<!-- modekeeper:product-intro:end -->
+
+
+ModeKeeper — self-serve слой контроля для ML-систем. Сначала работает в режиме **OBSERVE_ONLY** (бесплатная неделя): собирает телеметрию и формирует отчет «теряете ли вы деньги». Затем, по желанию, включается режим **CLOSED_LOOP** для безопасного автотюнинга с guardrails и откатами.
+
+## Возможности
+- Два режима: `OBSERVE_ONLY` и `CLOSED_LOOP`.
+- Модульная архитектура: core, telemetry, actuators, policy, safety, adapters.
+- Explain-log везде: каждое решение, ограничение и действие фиксируется.
+- Локальные демо-сценарии без внешних сервисов.
+
+## Установка
+```bash
+python -m venv .venv
+. .venv/bin/activate
+pip install -e .
+```
+
+## Быстрый старт
+```bash
+mk observe --duration 250ms --out report/_observe_quick
+mk demo run --scenario drift
+mk closed-loop run --scenario drift --dry-run --out report/_golden_dryrun
+```
+Canonical paid e2e (kind) + scripts: `docs/WORKFLOW.md`.
+
+## Quickstart
+Observe-only quickstart + RBAC verify-only replay:
+`docs/QUICKSTART.md`
+
+## E2E (kind)
+Canonical workflow: `docs/WORKFLOW.md` (paid path is one-shot `closed-loop run --apply`).
+Continuation snapshot: `docs/SNAPSHOT.md`.
+
+Canonical scripts:
+- `./scripts/e2e-smoke-kind.sh` (safe: kill switch blocks apply)
+- `./scripts/e2e-apply-kind.sh` (REAL kubectl patches)
+
+Warning: `./scripts/e2e-apply-kind.sh` performs real `kubectl` patches in the kind cluster.
+
+Observe параметры:
+- `--source` synthetic|file (default: synthetic)
+- `--path` обязателен для `--source file`
+- `--duration` принимает `1.5s`, `250ms`, `10m`; без суффикса = секунды
+- формат входа: `jsonl`/`csv` с полями `ts`, `step_time_ms`, `loss` (optional)
+
+## Демо
+```bash
+mk demo run --scenario straggler
+mk demo run --scenario burst
+```
+
+Выходные данные (контракт v0):
+- `report/` содержит JSON-отчеты и `explain.jsonl` (JSONL, `ensure_ascii=False`).
+- `observe_latest.json`, `demo_latest.json`, `closed_loop_latest.json` — копии последних отчетов.
+- Подробности k8s утилит/полей — см. `docs/WORKFLOW.md` и `docs/SNAPSHOT.md`.
+- Все отчеты имеют поля верхнего уровня: `schema_version`, `started_at`, `finished_at`, `duration_s`, `out_dir`.
+- В `OBSERVE_ONLY` добавляется `summary`:
+  - `money_leak_risk` (low|medium|high)
+  - `top_symptoms`
+  - `recommendations`
+- В `CLOSED_LOOP` дополнительно создаётся `summary.md` (короткий человекочитаемый итог прогона).
+- В `CLOSED_LOOP` также пишутся plan-only артефакты: `k8s_plan.json` и `k8s_plan.kubectl.sh` (в dry-run kubectl **не выполняется**).
+- В `CLOSED_LOOP` добавляются поля:
+  - `decision_summary` (RU)
+  - `proposed` (предлагаемые действия)
+  - `applied` (результаты применения/блокировки)
+  - `status` (например, `"ok"`)
+  - `kill_switch_active` (true/false)
+  - `blocked_reasons` (агрегация причин блокировок)
+  - `applied_reasons` (агрегация причин применений)
+  - `k8s_plan_path` (путь к `k8s_plan.json`)
+  - `k8s_plan_items` (кол-во items в плане)
+  - `k8s_kubectl_plan_path` (путь к `k8s_plan.kubectl.sh`)
+  - `k8s_namespace` (целевой namespace для скрипта/плана)
+  - `k8s_deployment` (целевой deployment для скрипта/плана)
+
+## Примечания
+- `closed-loop` по умолчанию работает в dry-run; для paid-apply используйте one-shot `closed-loop run --apply` (см. `docs/WORKFLOW.md`).
+- В dry-run `closed-loop` **не выполняет** kubectl: он только генерирует `k8s_plan.kubectl.sh`.
+- Для принудительной блокировки `--apply` используйте `MODEKEEPER_KILL_SWITCH=1` (в отчёте `blocked_reasons` будет `kill_switch`).
+- Все safety-ограничения локальные, настраиваемые и аудируемые.

modekeeper-0.1.1/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "modekeeper"
+version = "0.1.1"
+description = "ModeKeeper: self-serve observability and safe closed-loop tuning"
+readme = {file = "README.md", content-type = "text/markdown"}
+requires-python = ">=3.10"
+license = "LicenseRef-Proprietary"
+license-files = ["LICENSE"]
+authors = [{name = "ModeKeeper"}]
+keywords = ["mlops", "observability", "autotuning", "safety"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+]
+
+dependencies = []
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=7.4",
+  "ruff>=0.4.8",
+]
+
+[project.scripts]
+mk = "modekeeper.cli:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+"modekeeper.passports.templates" = ["*.json"]
+"modekeeper.chords" = ["*.json"]
+"modekeeper.license" = ["*.json"]
+
+[tool.ruff]
+line-length = 100
+select = ["E", "F", "I", "W"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+line-ending = "lf"
+
+[tool.pytest.ini_options]
+addopts = "-q"
+testpaths = ["tests"]

modekeeper-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

modekeeper-0.1.1/src/modekeeper/__init__.py

@@ -0,0 +1,4 @@
+"""ModeKeeper package."""
+
+__all__ = ["__version__"]
+__version__ = "0.1.1"

modekeeper-0.1.1/src/modekeeper/actuators/knobs.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timezone
+
+
+@dataclass
+class Knob:
+    name: str
+    min_value: int
+    max_value: int
+    step: int
+    value: int
+    last_changed_at: datetime | None = None
+
+    def clamp(self, target: int) -> int:
+        if target < self.min_value:
+            return self.min_value
+        if target > self.max_value:
+            return self.max_value
+        return target
+
+    def apply(self, target: int) -> int:
+        target = self.clamp(target)
+        self.value = target
+        self.last_changed_at = datetime.now(timezone.utc)
+        return self.value
+
+
+class ActuatorRegistry:
+    def __init__(self) -> None:
+        self._knobs: dict[str, Knob] = {}
+
+    def register(self, knob: Knob) -> None:
+        self._knobs[knob.name] = knob
+
+    def get(self, name: str) -> Knob | None:
+        return self._knobs.get(name)
+
+    def snapshot(self) -> dict[str, int]:
+        return {k: v.value for k, v in self._knobs.items()}
+
+    def restore(self, snapshot: dict[str, int]) -> None:
+        for name, value in snapshot.items():
+            if name in self._knobs:
+                self._knobs[name].value = value
+
+    def list_names(self) -> list[str]:
+        return list(self._knobs.keys())

modekeeper-0.1.1/src/modekeeper/adapters/kubernetes.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+
+def build_k8s_plan(
+    proposed_actions: list[object],
+    *,
+    namespace: str,
+    deployment: str,
+) -> list[dict]:
+    items_by_target: dict[tuple[str, str], dict] = {}
+    for action in proposed_actions:
+        knob = getattr(action, "knob", None)
+        target = getattr(action, "target", None)
+        key = (namespace, deployment)
+        item = items_by_target.get(key)
+        if item is None:
+            item = {
+                "apiVersion": "apps/v1",
+                "kind": "Deployment",
+                "namespace": namespace,
+                "name": deployment,
+                "reason": "coalesced",
+                "patch": {
+                    "metadata": {"annotations": {}},
+                    "spec": {"template": {"metadata": {"annotations": {}}}},
+                },
+            }
+            items_by_target[key] = item
+
+        annotation_key = f"modekeeper/knob.{knob}"
+        item["patch"]["metadata"]["annotations"][annotation_key] = f"{target}"
+        item["patch"]["spec"]["template"]["metadata"]["annotations"][annotation_key] = f"{target}"
+    return list(items_by_target.values())

modekeeper-0.1.1/src/modekeeper/adapters/lightning.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+import time
+from pathlib import Path
+
+from modekeeper.safety.explain import ExplainLog
+
+try:
+    import pytorch_lightning as pl
+except Exception:
+    try:
+        import lightning.pytorch as pl
+    except Exception:
+        pl = None
+
+LIGHTNING_AVAILABLE = pl is not None
+
+
+def build_lightning_callback(out_dir: Path) -> object | None:
+    if pl is None:
+        return None
+
+    explain = ExplainLog(out_dir / "explain.jsonl")
+
+    class ExplainCallback(pl.Callback):
+        def __init__(self) -> None:
+            super().__init__()
+            self._fit_start = None
+            self._batch_start = None
+
+        def on_train_start(self, trainer, pl_module) -> None:
+            now = time.monotonic()
+            if self._fit_start is None:
+                self._fit_start = now
+            explain.emit("pl_train_start", {"t": now})
+
+        def on_train_batch_start(self, trainer, pl_module, batch, batch_idx) -> None:
+            now = time.monotonic()
+            self._batch_start = now
+            explain.emit("pl_train_batch_start", {"t": now, "batch_idx": batch_idx})
+
+        def on_train_batch_end(self, trainer, pl_module, outputs, batch, batch_idx) -> None:
+            now = time.monotonic()
+            loss = _extract_loss(outputs)
+            payload = {"t": now, "batch_idx": batch_idx, "loss": loss}
+            if self._batch_start is not None:
+                payload["batch_duration_s"] = now - self._batch_start
+            explain.emit("pl_train_batch_end", payload)
+
+        def on_fit_end(self, trainer, pl_module) -> None:
+            now = time.monotonic()
+            payload = {"t": now}
+            if self._fit_start is not None:
+                payload["fit_duration_s"] = now - self._fit_start
+            explain.emit("pl_fit_end", payload)
+
+    return ExplainCallback()
+
+
+def _extract_loss(outputs: object) -> float | None:
+    if outputs is None:
+        return None
+    if isinstance(outputs, (int, float)):
+        return float(outputs)
+    if isinstance(outputs, dict):
+        if "loss" in outputs:
+            return _extract_loss(outputs["loss"])
+        return None
+    if isinstance(outputs, (list, tuple)) and outputs:
+        return _extract_loss(outputs[0])
+    item = getattr(outputs, "item", None)
+    if callable(item):
+        try:
+            return float(item())
+        except Exception:
+            return None
+    return None

modekeeper-0.1.1/src/modekeeper/audit/__init__.py

@@ -0,0 +1,2 @@
+"""Audit artifacts for closed-loop execution."""
+

modekeeper-0.1.1/src/modekeeper/audit/decision_trace.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+SCHEMA_VERSION = "decision_trace_event.v0"
+
+
+@dataclass
+class DecisionTraceWriter:
+    path: Path
+
+    def emit(self, event: dict[str, Any]) -> None:
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        with self.path.open("a", encoding="utf-8") as f:
+            f.write(
+                json.dumps(
+                    event,
+                    sort_keys=True,
+                    separators=(",", ":"),
+                    ensure_ascii=False,
+                )
+            )
+            f.write("\n")
+

modekeeper-0.1.1/src/modekeeper/chords/__init__.py

@@ -0,0 +1,2 @@
+"""Chord ID libraries."""
+

modekeeper-0.1.1/src/modekeeper/chords/catalog.py

@@ -0,0 +1,157 @@
+from __future__ import annotations
+
+import json
+from functools import lru_cache
+from pathlib import Path
+
+CATALOG_SCHEMA_VERSION = "chord_catalog.v1"
+VALIDATE_SCHEMA_VERSION = "chords_validate.v0"
+_REQUIRED_CHORD_KEYS = (
+    "id",
+    "intent",
+    "risk_tier",
+    "required_signals",
+    "invariants",
+    "knobs_touched",
+)
+_OPTIONAL_CHORD_KEYS = ("cooldown_ms", "budget")
+_ALLOWED_CHORD_KEYS = frozenset((*_REQUIRED_CHORD_KEYS, *_OPTIONAL_CHORD_KEYS))
+
+
+def _is_list_of_str(value: object) -> bool:
+    return isinstance(value, list) and all(isinstance(item, str) for item in value)
+
+
+def validate_catalog_dict(catalog: dict, source: str) -> list[str]:
+    errors: list[str] = []
+    if not isinstance(catalog, dict):
+        return [f"{source}: top-level JSON must be an object"]
+
+    top_unknown_keys = sorted(set(catalog.keys()) - {"schema_version", "chords"})
+    for key in top_unknown_keys:
+        errors.append(f"{source}: unknown top-level field '{key}'")
+
+    schema_version = catalog.get("schema_version")
+    if schema_version != CATALOG_SCHEMA_VERSION:
+        errors.append(f"{source}: schema_version must be '{CATALOG_SCHEMA_VERSION}'")
+
+    chords = catalog.get("chords")
+    if not isinstance(chords, list):
+        errors.append(f"{source}: chords must be an array")
+        return errors
+
+    seen_ids: set[str] = set()
+    for index, item in enumerate(chords):
+        path = f"{source}: chords[{index}]"
+        if not isinstance(item, dict):
+            errors.append(f"{path} must be an object")
+            continue
+
+        unknown_keys = sorted(set(item.keys()) - _ALLOWED_CHORD_KEYS)
+        for key in unknown_keys:
+            errors.append(f"{path}: unknown field '{key}'")
+
+        for key in _REQUIRED_CHORD_KEYS:
+            if key not in item:
+                errors.append(f"{path}: missing required field '{key}'")
+
+        chord_id = item.get("id")
+        if isinstance(chord_id, str):
+            if chord_id in seen_ids:
+                errors.append(f"{path}: duplicate chord id '{chord_id}'")
+            else:
+                seen_ids.add(chord_id)
+        else:
+            errors.append(f"{path}: id must be string")
+
+        intent = item.get("intent")
+        if not isinstance(intent, str):
+            errors.append(f"{path}: intent must be string")
+
+        risk_tier = item.get("risk_tier")
+        if not isinstance(risk_tier, str):
+            errors.append(f"{path}: risk_tier must be string")
+
+        required_signals = item.get("required_signals")
+        if not _is_list_of_str(required_signals):
+            errors.append(f"{path}: required_signals must be array of strings")
+
+        invariants = item.get("invariants")
+        if not _is_list_of_str(invariants):
+            errors.append(f"{path}: invariants must be array of strings")
+
+        knobs_touched = item.get("knobs_touched")
+        if not _is_list_of_str(knobs_touched):
+            errors.append(f"{path}: knobs_touched must be array of strings")
+
+        if "cooldown_ms" in item and not isinstance(item.get("cooldown_ms"), int):
+            errors.append(f"{path}: cooldown_ms must be int")
+
+        if "budget" in item and not isinstance(item.get("budget"), dict):
+            errors.append(f"{path}: budget must be object")
+
+    return errors
+
+
+def validate_catalog_file(path: Path) -> dict:
+    source = str(path)
+    errors: list[str] = []
+    payload: object = {}
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except FileNotFoundError:
+        errors.append(f"{source}: file not found")
+    except json.JSONDecodeError as exc:
+        errors.append(f"{source}: invalid JSON: {exc}")
+
+    chord_count = 0
+    chord_ids: list[str] = []
+    if isinstance(payload, dict):
+        chords = payload.get("chords")
+        if isinstance(chords, list):
+            chord_count = len(chords)
+            chord_ids = sorted(
+                {
+                    item.get("id")
+                    for item in chords
+                    if isinstance(item, dict) and isinstance(item.get("id"), str)
+                }
+            )
+
+    if errors:
+        return {
+            "schema_version": VALIDATE_SCHEMA_VERSION,
+            "ok": False,
+            "errors": errors,
+            "chord_count": chord_count,
+            "chord_ids": chord_ids,
+        }
+
+    if isinstance(payload, dict):
+        errors.extend(validate_catalog_dict(payload, source=source))
+    else:
+        errors.append(f"{source}: top-level JSON must be an object")
+
+    return {
+        "schema_version": VALIDATE_SCHEMA_VERSION,
+        "ok": len(errors) == 0,
+        "errors": errors,
+        "chord_count": chord_count,
+        "chord_ids": chord_ids,
+    }
+
+
+def load_catalog_file(path: Path) -> dict:
+    payload = json.loads(path.read_text(encoding="utf-8"))
+    if not isinstance(payload, dict):
+        raise ValueError(f"{path}: top-level JSON must be an object")
+    errors = validate_catalog_dict(payload, source=str(path))
+    if errors:
+        raise ValueError("; ".join(errors))
+    return payload
+
+
+@lru_cache(maxsize=1)
+def load_default_catalog() -> dict:
+    path = Path(__file__).with_name("catalog_v1.json")
+    return load_catalog_file(path)