tinet-agent-cli 0.1.0.dev36__py3-none-any.whl

taco/aikb/catalog.py

@@ -0,0 +1,380 @@
+from __future__ import annotations
+
+import json
+import re
+from importlib import resources
+from pathlib import Path, PurePosixPath
+from types import MappingProxyType
+from typing import Any
+from urllib.parse import urlsplit
+
+from jsonschema import Draft202012Validator
+
+from taco.aikb.models import AikbCatalog, AikbOperation, freeze
+from taco.core.errors import TacoError
+
+
+SUPPORTED_CATALOG_MAJOR = "1"
+SUPPORTED_SCHEMA_MAJOR = "1"
+EXECUTION_KINDS = frozenset({"http", "presigned-put-v1"})
+HTTP_METHODS = frozenset({"GET", "POST"})
+RESERVED_PARAMETERS = frozenset(
+    {"accesskeyid", "expires", "timestamp", "signature", "authorization"}
+)
+_ID_PATTERN = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")
+_ZH_PATTERN = re.compile(r"[\u3400-\u9fff]")
+
+
+def load_catalog(root: Path | None = None) -> AikbCatalog:
+    try:
+        if root is None:
+            package_root = resources.files("taco.assets").joinpath("aikb")
+            payload = json.loads(package_root.joinpath("catalog.json").read_text("utf-8"))
+            operation_payloads = {
+                entry: json.loads(
+                    package_root.joinpath("operations", f"{entry}.json").read_text("utf-8")
+                )
+                for entry in _catalog_entries(payload)
+            }
+            actual_entries = sorted(
+                _resource_json_entries(package_root.joinpath("operations"))
+            )
+        else:
+            payload = json.loads((root / "catalog.json").read_text(encoding="utf-8"))
+            entries = _catalog_entries(payload)
+            operation_payloads = {
+                entry: json.loads(
+                    (root / "operations" / f"{entry}.json").read_text(encoding="utf-8")
+                )
+                for entry in entries
+            }
+            operations_root = root / "operations"
+            actual_entries = sorted(
+                path.relative_to(operations_root).as_posix()[:-5]
+                for path in operations_root.rglob("*.json")
+            ) if operations_root.exists() else []
+        return _build_catalog(payload, operation_payloads, actual_entries)
+    except TacoError:
+        raise
+    except (OSError, ValueError, TypeError, KeyError) as error:
+        raise _catalog_error(str(error)) from error
+
+
+def _catalog_entries(payload: Any) -> list[str]:
+    if not isinstance(payload, dict):
+        raise _catalog_error("catalog 必须是对象")
+    version = payload.get("catalog_version")
+    if not isinstance(version, str) or version.split(".", 1)[0] != SUPPORTED_CATALOG_MAJOR:
+        raise _catalog_error("不支持的 catalog_version")
+    if payload.get("json_schema_dialect") != "https://json-schema.org/draft/2020-12/schema":
+        raise _catalog_error("不支持的 JSON Schema 方言")
+    entries = payload.get("operations")
+    if not isinstance(entries, list) or any(not isinstance(item, str) for item in entries):
+        raise _catalog_error("operations 必须是字符串数组")
+    if len(entries) != len(set(entries)):
+        raise _catalog_error("catalog operation 重复")
+    for entry in entries:
+        path = PurePosixPath(entry)
+        if path.is_absolute() or len(path.parts) != 2 or ".." in path.parts:
+            raise _catalog_error(f"非法 operation 路径：{entry}")
+        if not all(_ID_PATTERN.fullmatch(part) for part in path.parts):
+            raise _catalog_error(f"非法 operation 路径：{entry}")
+    return entries
+
+
+def _resource_json_entries(root: Any, prefix: str = "") -> list[str]:
+    if not root.is_dir():
+        return []
+    result: list[str] = []
+    for child in root.iterdir():
+        relative = f"{prefix}/{child.name}" if prefix else child.name
+        if child.is_dir():
+            result.extend(_resource_json_entries(child, relative))
+        elif child.name.endswith(".json"):
+            result.append(relative[:-5])
+    return result
+
+
+def _build_catalog(
+    payload: dict[str, Any],
+    operation_payloads: dict[str, Any],
+    actual_entries: list[str],
+) -> AikbCatalog:
+    entries = _catalog_entries(payload)
+    if sorted(entries) != actual_entries:
+        raise _catalog_error("catalog 登记项与 operation 文件不一致")
+    operations = tuple(
+        _build_operation(entry, operation_payloads[entry]) for entry in entries
+    )
+    ids = [operation.id for operation in operations]
+    if len(ids) != len(set(ids)):
+        raise _catalog_error("operation id 重复")
+    known_ids = set(ids)
+    for operation in operations:
+        for schema in (operation.http["query_schema"], operation.http["body_schema"]):
+            for source in _source_operations(schema):
+                if source not in known_ids:
+                    raise _catalog_error(f"未知来源 operation：{source}")
+    by_id = MappingProxyType({operation.id: operation for operation in operations})
+    return AikbCatalog(
+        catalog_version=payload["catalog_version"],
+        source=freeze(payload.get("source", {})),
+        defaults=freeze(payload.get("defaults", {})),
+        operations=operations,
+        by_id=by_id,
+    )
+
+
+def _build_operation(entry: str, payload: Any) -> AikbOperation:
+    if not isinstance(payload, dict):
+        raise _catalog_error(f"{entry} 必须是对象")
+    version = payload.get("schema_version")
+    if not isinstance(version, str) or version.split(".", 1)[0] != SUPPORTED_SCHEMA_MAJOR:
+        raise _catalog_error(f"{entry} schema_version 不受支持")
+    group, filename = entry.split("/")
+    operation_id = payload.get("id")
+    if operation_id != filename or payload.get("group") != group:
+        raise _catalog_error(f"{entry} 的 id/group 与文件名不一致")
+    for field in ("title", "description"):
+        if not isinstance(payload.get(field), str) or not payload[field].strip():
+            raise _catalog_error(f"{entry} 缺少 {field}")
+    keywords = payload.get("keywords")
+    if not isinstance(keywords, list) or any(not isinstance(item, str) for item in keywords):
+        raise _catalog_error(f"{entry} keywords 不合法")
+    source = payload.get("source")
+    if not isinstance(source, dict) or not all(
+        isinstance(source.get(field), str) and source[field].strip()
+        for field in ("url", "anchor", "snapshot_date")
+    ):
+        raise _catalog_error(f"{entry} source 不完整")
+    http = payload.get("http")
+    if not isinstance(http, dict):
+        raise _catalog_error(f"{entry} http 不合法")
+    method = http.get("method")
+    path = http.get("path")
+    if method not in HTTP_METHODS or not _safe_aikb_path(path):
+        raise _catalog_error(f"{entry} HTTP method/path 不合法")
+    query_schema = http.get("query_schema")
+    body_schema = http.get("body_schema")
+    for name, schema in (("query", query_schema), ("body", body_schema)):
+        if not isinstance(schema, dict) or schema.get("type") != "object":
+            raise _catalog_error(f"{entry} {name}_schema 必须是 object")
+        if schema.get("additionalProperties") is not False:
+            raise _catalog_error(f"{entry} {name}_schema 必须禁止未知参数")
+        Draft202012Validator.check_schema(schema)
+        _validate_schema_descriptions(schema, request=True, root=True)
+    query_fields = set(query_schema.get("properties", {}))
+    body_fields = set(body_schema.get("properties", {}))
+    if query_fields & body_fields:
+        raise _catalog_error(f"{entry} query/body 参数重名")
+    if any(field.lower() in RESERVED_PARAMETERS for field in query_fields | body_fields):
+        raise _catalog_error(f"{entry} 声明了保留认证参数")
+    response = payload.get("response")
+    if not isinstance(response, dict) or not isinstance(response.get("schema"), dict):
+        raise _catalog_error(f"{entry} response 不合法")
+    Draft202012Validator.check_schema(response["schema"])
+    _validate_schema_descriptions(response["schema"], request=False, root=True)
+    pointers = [response.get("request_id_pointer"), *response.get("sensitive_pointers", [])]
+    if any(not _schema_has_pointer(response["schema"], pointer) for pointer in pointers):
+        raise _catalog_error(f"{entry} response JSON Pointer 不合法")
+    risk = payload.get("risk")
+    if not isinstance(risk, dict) or risk.get("level") not in {"read", "write", "destructive"}:
+        raise _catalog_error(f"{entry} risk 不合法")
+    execution = payload.get("execution")
+    if not isinstance(execution, dict) or execution.get("kind") not in EXECUTION_KINDS:
+        raise _catalog_error(f"{entry} execution kind 不合法")
+    if execution["kind"] == "http" and set(execution) != {"kind"}:
+        raise _catalog_error(f"{entry} http executor 含未知配置")
+    if execution["kind"] == "presigned-put-v1":
+        _validate_presigned_put(entry, payload, execution, body_schema, response["schema"])
+    notes = payload.get("compatibility_notes", [])
+    if not isinstance(notes, list) or any(not isinstance(note, dict) for note in notes):
+        raise _catalog_error(f"{entry} compatibility_notes 不合法")
+    if any(str(note.get("verification", "")).lower() == "pending" for note in notes):
+        raise _catalog_error(f"{entry} 存在未闭环兼容性问题")
+    examples = payload.get("examples")
+    if not isinstance(examples, list) or any(not isinstance(example, dict) for example in examples):
+        raise _catalog_error(f"{entry} examples 不合法")
+    _validate_examples(entry, examples, query_schema, body_schema, execution["kind"])
+    return AikbOperation(
+        id=operation_id,
+        title=payload["title"],
+        description=payload["description"],
+        group=group,
+        keywords=tuple(keywords),
+        source=freeze(source),
+        http=freeze(http),
+        response=freeze(response),
+        risk=freeze(risk),
+        execution=freeze(execution),
+        examples=tuple(freeze(examples)),
+        file_input=freeze(payload.get("file_input")),
+        compatibility_notes=tuple(freeze(notes)),
+    )
+
+
+def _safe_aikb_path(value: Any) -> bool:
+    if not isinstance(value, str) or not value.startswith("/aikb/"):
+        return False
+    parsed = urlsplit(value)
+    return not parsed.scheme and not parsed.netloc and not parsed.query and not parsed.fragment and ".." not in PurePosixPath(parsed.path).parts
+
+
+def _validate_schema_descriptions(schema: dict[str, Any], *, request: bool, root: bool = False) -> None:
+    if not root:
+        text_required = ("description",) if not request else ("title", "description")
+        schema_type = schema.get("type")
+        valid_type = isinstance(schema_type, str) and bool(schema_type.strip())
+        valid_type = valid_type or (
+            isinstance(schema_type, list)
+            and bool(schema_type)
+            and all(isinstance(item, str) and item.strip() for item in schema_type)
+        )
+        if not valid_type or any(
+            not isinstance(schema.get(field), str) or not schema[field].strip()
+            for field in text_required
+        ):
+            raise _catalog_error("schema 字段缺少类型或说明")
+        if not _ZH_PATTERN.search(schema["description"]):
+            raise _catalog_error("schema description 必须包含中文")
+    if "enum" in schema:
+        descriptions = schema.get("x-enum-descriptions")
+        if not isinstance(descriptions, dict) or set(map(str, schema["enum"])) != set(descriptions):
+            raise _catalog_error("enum 缺少完整说明")
+    for child in schema.get("properties", {}).values():
+        _validate_schema_descriptions(child, request=request)
+    if isinstance(schema.get("items"), dict):
+        _validate_schema_descriptions(schema["items"], request=request)
+    for keyword in ("oneOf", "anyOf", "allOf"):
+        for child in schema.get(keyword, []):
+            _validate_schema_descriptions(child, request=request, root=True)
+    for child in schema.get("$defs", {}).values():
+        _validate_schema_descriptions(child, request=request, root=True)
+
+
+def _schema_has_pointer(schema: dict[str, Any], pointer: Any) -> bool:
+    if (
+        not isinstance(pointer, str)
+        or not pointer.startswith("/")
+        or re.search(r"~(?:[^01]|$)", pointer)
+    ):
+        return False
+    current = schema
+    for raw in pointer[1:].split("/"):
+        token = raw.replace("~1", "/").replace("~0", "~")
+        properties = current.get("properties")
+        if not isinstance(properties, dict) or token not in properties:
+            return False
+        current = properties[token]
+    return True
+
+
+def _validate_presigned_put(
+    entry: str,
+    payload: dict[str, Any],
+    execution: dict[str, Any],
+    body_schema: dict[str, Any],
+    response_schema: dict[str, Any],
+) -> None:
+    if set(execution) != {"kind", "request_bindings", "upload", "output"}:
+        raise _catalog_error(f"{entry} presigned-put-v1 含未知配置")
+    file_input = payload.get("file_input")
+    if not isinstance(file_input, dict) or file_input.get("required") is not True:
+        raise _catalog_error(f"{entry} 缺少必需 file_input")
+    bindings = execution.get("request_bindings")
+    if not isinstance(bindings, list) or not bindings:
+        raise _catalog_error(f"{entry} request_bindings 不合法")
+    for binding in bindings:
+        if not isinstance(binding, dict) or set(binding) != {"source", "target"}:
+            raise _catalog_error(f"{entry} request binding 不合法")
+        if binding["source"] not in {"file.basename", "file.size"} or not _schema_has_pointer(body_schema, binding["target"]):
+            raise _catalog_error(f"{entry} request binding 不安全")
+    upload = execution.get("upload")
+    required_upload = {
+        "url_pointer",
+        "method",
+        "success_statuses",
+        "follow_redirects",
+        "forward_auth_headers",
+        "timeout_profile",
+    }
+    if not isinstance(upload, dict) or set(upload) != required_upload:
+        raise _catalog_error(f"{entry} upload 配置不完整")
+    if (
+        not _schema_has_pointer(response_schema, upload["url_pointer"])
+        or upload["method"] != "PUT"
+        or not isinstance(upload["success_statuses"], list)
+        or not upload["success_statuses"]
+        or any(not isinstance(status, int) for status in upload["success_statuses"])
+        or upload["follow_redirects"] is not False
+        or upload["forward_auth_headers"] is not False
+        or upload["timeout_profile"] != "upload"
+    ):
+        raise _catalog_error(f"{entry} upload 配置不安全")
+    output = execution.get("output")
+    if not isinstance(output, dict) or not output:
+        raise _catalog_error(f"{entry} output 配置不合法")
+    for field in output.values():
+        if not isinstance(field, dict):
+            raise _catalog_error(f"{entry} output 来源不安全")
+        if field.get("constant") is True and field.get("type") == "boolean":
+            continue
+        if field.get("source") not in {
+            "prepare_response",
+            "file.basename",
+            "file.size",
+        }:
+            raise _catalog_error(f"{entry} output 来源不安全")
+        if field["source"] == "prepare_response" and not _schema_has_pointer(
+            response_schema, field.get("pointer")
+        ):
+            raise _catalog_error(f"{entry} output pointer 不合法")
+
+
+def _source_operations(schema: Any):
+    if isinstance(schema, dict):
+        source = schema.get("x-taco-source-operation")
+        if isinstance(source, str):
+            yield source
+        for value in schema.values():
+            yield from _source_operations(value)
+    elif isinstance(schema, list):
+        for value in schema:
+            yield from _source_operations(value)
+
+
+def _validate_examples(
+    entry: str,
+    examples: list[dict[str, Any]],
+    query_schema: dict[str, Any],
+    body_schema: dict[str, Any],
+    execution_kind: str,
+) -> None:
+    query_fields = set(query_schema.get("properties", {}))
+    body_fields = set(body_schema.get("properties", {}))
+    for example in examples:
+        if not isinstance(example.get("title"), str):
+            raise _catalog_error(f"{entry} example 缺少 title")
+        params = example.get("params", {})
+        if execution_kind == "presigned-put-v1" and "file" in example:
+            continue
+        if not isinstance(params, dict):
+            raise _catalog_error(f"{entry} example params 不合法")
+        unknown = set(params) - query_fields - body_fields
+        if unknown:
+            raise _catalog_error(f"{entry} example 含未知参数")
+        errors = [
+            *Draft202012Validator(query_schema).iter_errors({key: value for key, value in params.items() if key in query_fields}),
+            *Draft202012Validator(body_schema).iter_errors({key: value for key, value in params.items() if key in body_fields}),
+        ]
+        if errors:
+            raise _catalog_error(f"{entry} example 未通过 schema")
+
+
+def _catalog_error(detail: str) -> TacoError:
+    return TacoError(
+        code="AIKB_CATALOG_INVALID",
+        message="内置 AIKB operation catalog 不合法。",
+        exit_code=2,
+        hint=detail,
+    )

taco/aikb/executors.py

@@ -0,0 +1,157 @@
+from __future__ import annotations
+
+import math
+import os
+from typing import Any
+from urllib.parse import urlsplit
+
+import httpx
+from jsonschema import Draft202012Validator
+
+from taco.aikb.file_input import OpenFileInput
+from taco.aikb.models import AikbOperation
+from taco.aikb.parameters import thaw
+from taco.core.developer_center_client import DeveloperCenterClient
+from taco.core.errors import TacoError
+from taco.core.http_headers import with_cli_user_agent
+
+
+DEFAULT_UPLOAD_TIMEOUT_SECONDS = 600.0
+
+
+def execute_http(
+    operation: AikbOperation,
+    client: DeveloperCenterClient,
+    *,
+    query: dict[str, Any],
+    body: dict[str, Any],
+) -> dict[str, Any]:
+    payload = client.request_json(
+        operation.http["method"],
+        operation.http["path"],
+        query=query or None,
+        json_body=body or None,
+    )
+    return validate_response(operation, payload)
+
+
+def execute_presigned_put(
+    operation: AikbOperation,
+    client: DeveloperCenterClient,
+    *,
+    query: dict[str, Any],
+    body: dict[str, Any],
+    file: OpenFileInput,
+    upload_http_client: httpx.Client | None = None,
+    upload_timeout: float | None = None,
+) -> dict[str, Any]:
+    timeout = _resolve_upload_timeout(upload_timeout)
+    bound_body = dict(body)
+    bound_body.update({"fileName": file.name, "fileSize": file.size})
+    prepared = client.request_json(
+        operation.http["method"], operation.http["path"], query=query or None, json_body=bound_body
+    )
+    validate_response(operation, prepared)
+    try:
+        upload_url = prepared["result"]["uploadUrl"]
+        file_key = prepared["result"]["fileKey"]
+    except (KeyError, TypeError):
+        raise _response_error(_request_id(prepared)) from None
+    if not isinstance(upload_url, str) or not isinstance(file_key, str) or not file_key:
+        raise _response_error(_request_id(prepared))
+    parsed = urlsplit(upload_url)
+    if parsed.scheme != "https" or not parsed.hostname or parsed.username or parsed.password:
+        raise TacoError(code="AIKB_UPLOAD_URL_INVALID", message="临时上传地址不安全。", exit_code=4)
+    file.verify_unchanged()
+    owns_client = upload_http_client is None
+    upload_client = upload_http_client or httpx.Client(follow_redirects=False, timeout=timeout)
+    try:
+        with file.stream() as stream:
+            response = upload_client.put(
+                upload_url,
+                content=stream,
+                headers=with_cli_user_agent({"Content-Length": str(file.size)}),
+                follow_redirects=False,
+                timeout=timeout,
+            )
+    except httpx.HTTPError:
+        raise TacoError(
+            code="AIKB_UPLOAD_FAILED",
+            message="文档 PUT 上传失败，结果不明确，未自动重试。",
+            exit_code=4,
+        ) from None
+    finally:
+        if owns_client:
+            upload_client.close()
+    if response.status_code != 200:
+        raise TacoError(
+            code="AIKB_UPLOAD_FAILED",
+            message=f"文档 PUT 上传失败，HTTP 状态码 {response.status_code}。",
+            exit_code=4,
+            status=response.status_code,
+        )
+    return {
+        "operation": operation.id,
+        "file_name": file.name,
+        "file_size": file.size,
+        "file_key": file_key,
+        "uploaded": True,
+    }
+
+
+def validate_response(operation: AikbOperation, payload: Any) -> dict[str, Any]:
+    request_id = _request_id(payload)
+    error = next(
+        Draft202012Validator(thaw(operation.response["schema"])).iter_errors(payload),
+        None,
+    )
+    if error is not None:
+        pointer = "/" + "/".join(str(item) for item in error.absolute_path)
+        raise TacoError(
+            code="AIKB_RESPONSE_INVALID",
+            message=f"AIKB 响应 {pointer or '/'} 校验失败，期望 {error.validator}。",
+            exit_code=4,
+            request_id=request_id,
+            path=operation.http["path"],
+        )
+    business = dict(payload)
+    business.pop("requestId", None)
+    return {"request_id": request_id, "data": business}
+
+
+def _request_id(payload: Any) -> str | None:
+    if isinstance(payload, dict) and isinstance(payload.get("requestId"), str):
+        return payload["requestId"]
+    return None
+
+
+def _response_error(request_id: str | None) -> TacoError:
+    return TacoError(
+        code="AIKB_RESPONSE_INVALID",
+        message="获取上传地址响应缺少必要字段。",
+        exit_code=4,
+        request_id=request_id,
+    )
+
+
+def _resolve_upload_timeout(value: float | None) -> float:
+    raw: float | str = (
+        value
+        if value is not None
+        else os.getenv(
+            "TACO_AIKB_UPLOAD_TIMEOUT_SECONDS",
+            str(DEFAULT_UPLOAD_TIMEOUT_SECONDS),
+        )
+    )
+    try:
+        timeout = float(raw)
+    except (TypeError, ValueError):
+        timeout = 0.0
+    if not math.isfinite(timeout) or timeout <= 0:
+        raise TacoError(
+            code="AIKB_UPLOAD_TIMEOUT_INVALID",
+            message="AIKB 上传超时必须是有限的正数秒。",
+            exit_code=2,
+            hint="请检查 --upload-timeout 或 TACO_AIKB_UPLOAD_TIMEOUT_SECONDS。",
+        )
+    return timeout

taco/aikb/file_input.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+import os
+import stat
+from dataclasses import dataclass
+from pathlib import Path
+
+from taco.core.errors import TacoError
+
+
+@dataclass(slots=True)
+class OpenFileInput:
+    path: Path
+    descriptor: int
+    name: str
+    size: int
+    _snapshot: os.stat_result
+
+    @classmethod
+    def open(cls, path: Path) -> OpenFileInput:
+        flags = os.O_RDONLY | getattr(os, "O_CLOEXEC", 0) | getattr(os, "O_NOFOLLOW", 0)
+        try:
+            descriptor = os.open(path, flags)
+            snapshot = os.fstat(descriptor)
+        except OSError:
+            raise _file_error("无法安全打开上传文件。") from None
+        if not stat.S_ISREG(snapshot.st_mode):
+            os.close(descriptor)
+            raise _file_error("上传目标必须是普通文件。")
+        return cls(path, descriptor, path.name, snapshot.st_size, snapshot)
+
+    def verify_unchanged(self) -> None:
+        current = os.fstat(self.descriptor)
+        fields = ("st_dev", "st_ino", "st_size", "st_mtime_ns", "st_mode")
+        if any(getattr(current, field) != getattr(self._snapshot, field) for field in fields):
+            raise _file_error("上传文件在申请临时地址期间发生变化。")
+
+    def stream(self):
+        os.lseek(self.descriptor, 0, os.SEEK_SET)
+        return os.fdopen(os.dup(self.descriptor), "rb")
+
+    def close(self) -> None:
+        if self.descriptor >= 0:
+            descriptor, self.descriptor = self.descriptor, -1
+            os.close(descriptor)
+
+    def __enter__(self) -> OpenFileInput:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+
+def _file_error(message: str) -> TacoError:
+    return TacoError(code="AIKB_FILE_INVALID", message=message, exit_code=2)

taco/aikb/models.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from types import MappingProxyType
+from typing import Any, Mapping
+
+
+JsonMapping = Mapping[str, Any]
+
+
+@dataclass(frozen=True, slots=True)
+class AikbOperation:
+    id: str
+    title: str
+    description: str
+    group: str
+    keywords: tuple[str, ...]
+    source: JsonMapping
+    http: JsonMapping
+    response: JsonMapping
+    risk: JsonMapping
+    execution: JsonMapping
+    examples: tuple[JsonMapping, ...]
+    file_input: JsonMapping | None = None
+    compatibility_notes: tuple[JsonMapping, ...] = ()
+
+
+@dataclass(frozen=True, slots=True)
+class AikbCatalog:
+    catalog_version: str
+    source: JsonMapping
+    defaults: JsonMapping
+    operations: tuple[AikbOperation, ...]
+    by_id: Mapping[str, AikbOperation]
+
+
+def freeze(value: Any) -> Any:
+    if isinstance(value, dict):
+        return MappingProxyType({key: freeze(item) for key, item in value.items()})
+    if isinstance(value, list):
+        return tuple(freeze(item) for item in value)
+    return value