multi-agent-platform 0.1.0__py3-none-any.whl

map_client/config.py

@@ -0,0 +1,21 @@
+import os
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+def load_config(config_path: Path | None = None) -> dict[str, Any]:
+    path = config_path or Path.home() / ".map" / "config.yaml"
+    config: dict[str, Any] = {}
+    if path.exists():
+        config = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+    api_url = config.get("api_url") or os.environ.get("MAP_API_URL", "http://localhost:8000")
+    token = config.get("token") or os.environ.get("MAP_TOKEN")
+    project_key = config.get("project_key") or os.environ.get("MAP_PROJECT_KEY")
+    return {
+        "api_url": str(api_url).rstrip("/"),
+        "token": token,
+        "project_key": project_key,
+        "config_path": path,
+    }

map_client/errors.py

@@ -0,0 +1,283 @@
+"""STATE_MACHINE.* error registry + recovery hint helper (experiment 156172e9 I1(a)).
+
+The MAP state machine raises :class:`server.services.errors.StateTransitionError`
+on illegal transitions (phase / review-item / topic-status). The exception
+carries an optional ``error_code`` string (e.g. ``REVIEW_REJECT_RESULT_MISUSE``)
+that callers can branch on programmatically instead of pattern-matching the
+human-readable ``detail`` text.
+
+This module:
+
+1. Defines the canonical ``STATE_MACHINE_*`` error code constants so callers
+   can ``from map_client.errors import STATE_MACHINE_REJECT_RESULT_MISUSE``
+   instead of typo-prone string literals.
+2. Maintains a :data:`RECOVERY_HINTS` registry mapping each code to a
+   short, actionable recovery hint (one canonical line that says "try X" or
+   "see Y").
+3. Exposes :func:`recovery_hint` so SDK callers — and the CLI ``_run``
+   handler — can look up the hint by error code (or by passing the
+   ``MAPHTTPError`` instance directly).
+
+The hint registry is the **single source of truth** for the SDK-side
+recovery narrative; the server-side ``StateTransitionError.hint`` field is
+still authoritative for HTTP errors. The SDK helper only kicks in when:
+
+- the caller wants a hint for a known STATE_MACHINE.* code without making
+  an HTTP call (e.g. unit tests, scripted pre-flight, agent planning); or
+- the server did not include a ``hint`` field in the response (older API
+  versions / legacy fallbacks).
+
+Fixtures live in ``tests/fixtures/state_machine_errors.yaml`` and are
+loaded by tests; the registry in this module is the canonical Python
+mapping.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from map_client.exceptions import MAPHTTPError
+
+
+# --- STATE_MACHINE.* error code constants ---------------------------------
+#
+# Naming convention: ``STATE_MACHINE_<DOMAIN>_<REASON>``. Each constant
+# corresponds to one server-side ``StateTransitionError(error_code=...)``
+# call site; the test suite asserts every constant has a non-empty hint.
+#
+# When the server adds a new code, add the constant here + a hint in
+# RECOVERY_HINTS in the same commit; do not let the constants drift.
+
+# Phase machine: experiment / topic phase transitions.
+STATE_MACHINE_INVALID_PHASE_TRANSITION = "STATE_MACHINE_INVALID_PHASE_TRANSITION"
+STATE_MACHINE_TERMINAL_PHASE = "STATE_MACHINE_TERMINAL_PHASE"
+STATE_MACHINE_PLAN_REQUIRED = "STATE_MACHINE_PLAN_REQUIRED"
+STATE_MACHINE_MISSING_EVIDENCE = "STATE_MACHINE_MISSING_EVIDENCE"
+STATE_MACHINE_REVISE_OUT_OF_PHASE = "STATE_MACHINE_REVISE_OUT_OF_PHASE"
+STATE_MACHINE_LOG_OUT_OF_PHASE = "STATE_MACHINE_LOG_OUT_OF_PHASE"
+STATE_MACHINE_TOPIC_INVALID_TRANSITION = "STATE_MACHINE_TOPIC_INVALID_TRANSITION"
+STATE_MACHINE_ACCEPTANCE_UNKNOWN_TYPE = "STATE_MACHINE_ACCEPTANCE_UNKNOWN_TYPE"
+
+# Review-item machine: per-item status transitions.
+STATE_MACHINE_REVIEW_ITEM_INVALID_TRANSITION = "STATE_MACHINE_REVIEW_ITEM_INVALID_TRANSITION"
+STATE_MACHINE_REVIEW_ITEM_ACTOR_DENIED = "STATE_MACHINE_REVIEW_ITEM_ACTOR_DENIED"
+STATE_MACHINE_REVIEW_ITEM_NOT_UNREASONABLE = "STATE_MACHINE_REVIEW_ITEM_NOT_UNREASONABLE"
+STATE_MACHINE_REVIEW_ITEM_NO_STATUS = "STATE_MACHINE_REVIEW_ITEM_NO_STATUS"
+STATE_MACHINE_REVIEW_ITEM_REBUT_AFTER_REVIEW = "STATE_MACHINE_REVIEW_ITEM_REBUT_AFTER_REVIEW"
+
+# Review aggregate: review-submission / withdraw gates.
+STATE_MACHINE_REVIEW_NOT_IN_REVIEW_PHASE = "STATE_MACHINE_REVIEW_NOT_IN_REVIEW_PHASE"
+STATE_MACHINE_REVIEW_WITHDRAW_NOT_IN_REVIEW_PHASE = (
+    "STATE_MACHINE_REVIEW_WITHDRAW_NOT_IN_REVIEW_PHASE"
+)
+
+# Specific misuse subcode (carried forward from I1(d) — the first
+# STATE_MACHINE.* code with a server-side hint).
+STATE_MACHINE_REJECT_RESULT_MISUSE = "REVIEW_REJECT_RESULT_MISUSE"
+
+# I1(d) — archived review cannot be mutated. Triggered by
+# update_review_item / withdraw_review when the parent review row
+# carries archived_at != NULL (set by plan_revise auto-archive, manual
+# admin archive, or the migration 034 backfill marker).
+STATE_MACHINE_REVIEW_ALREADY_ARCHIVED = "REVIEW_ALREADY_ARCHIVED"
+
+
+# Default error code used by server-side ``StateTransitionError`` when no
+# explicit ``error_code`` is supplied (legacy / pre-I1(d) call sites).
+STATE_MACHINE_GENERIC = "state_machine_error"
+
+
+# All known STATE_MACHINE.* error codes. Used by ``test_recovery_hint_*``
+# to assert every code has a hint. Keep in sync with the constants above
+# + any new ones; the test will fail loudly if you forget.
+STATE_MACHINE_ERROR_CODES: frozenset[str] = frozenset(
+    {
+        # Phase
+        STATE_MACHINE_INVALID_PHASE_TRANSITION,
+        STATE_MACHINE_TERMINAL_PHASE,
+        STATE_MACHINE_PLAN_REQUIRED,
+        STATE_MACHINE_MISSING_EVIDENCE,
+        STATE_MACHINE_REVISE_OUT_OF_PHASE,
+        STATE_MACHINE_LOG_OUT_OF_PHASE,
+        STATE_MACHINE_TOPIC_INVALID_TRANSITION,
+        STATE_MACHINE_ACCEPTANCE_UNKNOWN_TYPE,
+        # Review item
+        STATE_MACHINE_REVIEW_ITEM_INVALID_TRANSITION,
+        STATE_MACHINE_REVIEW_ITEM_ACTOR_DENIED,
+        STATE_MACHINE_REVIEW_ITEM_NOT_UNREASONABLE,
+        STATE_MACHINE_REVIEW_ITEM_NO_STATUS,
+        STATE_MACHINE_REVIEW_ITEM_REBUT_AFTER_REVIEW,
+        # Review aggregate
+        STATE_MACHINE_REVIEW_NOT_IN_REVIEW_PHASE,
+        STATE_MACHINE_REVIEW_WITHDRAW_NOT_IN_REVIEW_PHASE,
+        # Specific misuse subcode
+        STATE_MACHINE_REJECT_RESULT_MISUSE,
+        # I1(d) — archived review refusal
+        STATE_MACHINE_REVIEW_ALREADY_ARCHIVED,
+        # Generic
+        STATE_MACHINE_GENERIC,
+    }
+)
+
+
+# Hint registry: code → recovery hint (one canonical actionable line).
+#
+# Conventions:
+# - One short sentence per code (≤ 200 chars).
+# - Lead with the action ("Run X", "Use Y", "Wait for Z"); avoid generic
+#   "Contact admin".
+# - Reference the canonical CLI command when one exists.
+# - When no command exists, point to the docs path.
+#
+# Tests assert that every value is a non-empty string. Empty / ``None``
+# hints fail ``test_recovery_hint_covers_all_state_machine_codes``.
+RECOVERY_HINTS: dict[str, str] = {
+    STATE_MACHINE_INVALID_PHASE_TRANSITION: (
+        "实验当前 phase 不允许此操作；运行 `map --persona host experiment "
+        "show --id <uuid>` 查看 current_phase + allowed transitions。"
+    ),
+    STATE_MACHINE_TERMINAL_PHASE: (
+        "实验已进入终态 (done / cancelled)；变更实验需创建新实验。"
+    ),
+    STATE_MACHINE_PLAN_REQUIRED: (
+        "实验需要至少 1 个 plan 版本；先 `map --persona host experiment "
+        "plan revise --id <uuid> --plan-file <path>` 再 submit-review。"
+    ),
+    STATE_MACHINE_MISSING_EVIDENCE: (
+        "complete 需要 evidence metadata (pytest_summary / alembic_current / "
+        "api_health / image_digest 至少一项)；参考 `map --persona host "
+        "experiment pre-complete --help`。非部署型实验用 "
+        "`--allow-missing-evidence`。"
+    ),
+    STATE_MACHINE_REVISE_OUT_OF_PHASE: (
+        "plan 只能在 draft / review / running 阶段修订；`map --persona host "
+        "experiment status --id <uuid>` 查看 phase。"
+    ),
+    STATE_MACHINE_LOG_OUT_OF_PHASE: (
+        "log 只能在 running / result_review / done 阶段追加；先 `start` 实验 "
+        "或等待 reviewer accept-result。"
+    ),
+    STATE_MACHINE_TOPIC_INVALID_TRANSITION: (
+        "话题状态机拒绝此转换；`map --persona host topic show --id <uuid>` "
+        "查看 allowed transitions（如 open↔closed 不能跨 archive）。"
+    ),
+    STATE_MACHINE_ACCEPTANCE_UNKNOWN_TYPE: (
+        "acceptance_type 必须是 migration / smoke / unit_test / integration / "
+        "manual 之一；详见 `map docs error-codes --search acceptance`。"
+    ),
+    STATE_MACHINE_REVIEW_ITEM_INVALID_TRANSITION: (
+        "review item 状态机拒绝此转换；`map --persona host experiment review "
+        "list --id <uuid>` 查看当前 status + allowed transitions。"
+    ),
+    STATE_MACHINE_REVIEW_ITEM_ACTOR_DENIED: (
+        "当前 persona 无权做此 item 转换；reviewer 转换需 is_reviewer，"
+        "host 转换需 is_creator。换 persona 或请 admin 介入。"
+    ),
+    STATE_MACHINE_REVIEW_ITEM_NOT_UNREASONABLE: (
+        "只有 unreasonable item 有 mutable status；reasonable item 是只读 "
+        "observation，调用方不需要 resolve。"
+    ),
+    STATE_MACHINE_REVIEW_ITEM_NO_STATUS: (
+        "review item 当前没有 status（通常是数据迁移遗留）；"
+        "`map --persona reviewer experiment review add` 重新提交 review。"
+    ),
+    STATE_MACHINE_REVIEW_ITEM_REBUT_AFTER_REVIEW: (
+        "实验已过 review 阶段，单 item rebut 不再生效；若要驳回整个 result，"
+        "让 reviewer / admin 调用 `map --persona reviewer experiment "
+        "reject-result --id <uuid>`。"
+    ),
+    STATE_MACHINE_REVIEW_NOT_IN_REVIEW_PHASE: (
+        "review 只能在 review phase 提交；`map --persona host experiment "
+        "show --id <uuid>` 确认 phase=review。"
+    ),
+    STATE_MACHINE_REVIEW_WITHDRAW_NOT_IN_REVIEW_PHASE: (
+        "withdraw_review 只能在 review phase 执行；实验已进入下游 phase，"
+        "review 不能再撤。"
+    ),
+    STATE_MACHINE_REJECT_RESULT_MISUSE: (
+        "单 item 驳回请用 resolve-item --status rebutted (review 阶段); "
+        "整个实验驳回请让 reviewer / admin 调用 reject-result, "
+        "host creator 不可拒绝自己的 result。"
+    ),
+    STATE_MACHINE_REVIEW_ALREADY_ARCHIVED: (
+        "查看 `map experiment review list --include-archived --plan-version <v>` 历史; "
+        "若需要修改 item, 请在新的 plan_version 提交新 review。"
+    ),
+    STATE_MACHINE_GENERIC: (
+        "状态机拒绝此操作；详见 `map docs error-codes` 或 `map --persona "
+        "host experiment show --id <uuid>`。"
+    ),
+}
+
+
+# Default generic hint for codes outside the registry. Used when
+# ``recovery_hint`` is called with an unknown code (forward compatibility
+# for codes the SDK does not yet know about).
+_GENERIC_FALLBACK_HINT = (
+    "未识别的 state_machine_error_code；查看 `map docs error-codes` 列表，"
+    "或升级 SDK 到最新版本以获得专属 hint。"
+)
+
+
+def recovery_hint(
+    exc_or_code: MAPHTTPError | str | None,
+) -> str:
+    """Return the recovery hint for a STATE_MACHINE.* error.
+
+    Accepts either:
+
+    - a :class:`MAPHTTPError` instance (reads its ``error_code`` attribute);
+    - a raw error code string;
+    - ``None`` (returns the generic fallback).
+
+    Lookup order:
+
+    1. If the value carries an ``error_code`` attribute (or is a string),
+       use it as the lookup key.
+    2. Look up the key in :data:`RECOVERY_HINTS`.
+    3. If the key is not in the registry, return the generic fallback so
+       callers never see a ``KeyError`` / ``None`` from this helper.
+
+    The function never raises — callers can use it as the single entry
+    point in error handlers without ``try``/``except``.
+    """
+    if exc_or_code is None:
+        return _GENERIC_FALLBACK_HINT
+    code = getattr(exc_or_code, "error_code", None)
+    if code is None and isinstance(exc_or_code, str):
+        code = exc_or_code
+    if not code:
+        return _GENERIC_FALLBACK_HINT
+    return RECOVERY_HINTS.get(code, _GENERIC_FALLBACK_HINT)
+
+
+__all__ = [
+    "STATE_MACHINE_ERROR_CODES",
+    "RECOVERY_HINTS",
+    "recovery_hint",
+    # Phase
+    "STATE_MACHINE_INVALID_PHASE_TRANSITION",
+    "STATE_MACHINE_TERMINAL_PHASE",
+    "STATE_MACHINE_PLAN_REQUIRED",
+    "STATE_MACHINE_MISSING_EVIDENCE",
+    "STATE_MACHINE_REVISE_OUT_OF_PHASE",
+    "STATE_MACHINE_LOG_OUT_OF_PHASE",
+    "STATE_MACHINE_TOPIC_INVALID_TRANSITION",
+    "STATE_MACHINE_ACCEPTANCE_UNKNOWN_TYPE",
+    # Review item
+    "STATE_MACHINE_REVIEW_ITEM_INVALID_TRANSITION",
+    "STATE_MACHINE_REVIEW_ITEM_ACTOR_DENIED",
+    "STATE_MACHINE_REVIEW_ITEM_NOT_UNREASONABLE",
+    "STATE_MACHINE_REVIEW_ITEM_NO_STATUS",
+    "STATE_MACHINE_REVIEW_ITEM_REBUT_AFTER_REVIEW",
+    # Review aggregate
+    "STATE_MACHINE_REVIEW_NOT_IN_REVIEW_PHASE",
+    "STATE_MACHINE_REVIEW_WITHDRAW_NOT_IN_REVIEW_PHASE",
+    # Misuse subcode
+    "STATE_MACHINE_REJECT_RESULT_MISUSE",
+    # I1(d) archived review refusal
+    "STATE_MACHINE_REVIEW_ALREADY_ARCHIVED",
+    # Generic
+    "STATE_MACHINE_GENERIC",
+]

map_client/exceptions.py

@@ -0,0 +1,130 @@
+"""SDK 异常体系（P2 #2 错误统一映射）。
+
+层级：
+    MAPError
+    └── MAPHTTPError          (4xx/5xx 通用，保留 status_code + detail)
+        ├── MAPClientError    (4xx 客户端错误)
+        │   ├── MAPValidationError        (400 / 422)
+        │   ├── MAPAuthenticationError    (401)
+        │   ├── MAPPermissionError        (403)
+        │   ├── MAPNotFoundError          (404)
+        │   ├── MAPConflictError          (409)
+        │   └── MAPRateLimitError         (429)
+        └── MAPServerError    (5xx 服务端错误)
+
+设计要点：
+- 所有子类都是 ``MAPHTTPError`` 的子类，``except MAPHTTPError`` 仍能 catch
+  全部 HTTP 错误（向后兼容）。
+- ``MAPHTTPError`` 本身不再直接 raise；``_raise_for_status`` 根据 status_code
+  实例化具体子类。CLI 可以 ``except MAPNotFoundError`` 写语义化错误处理，
+  不用再 ``if exc.status_code == 404``。
+- 未识别的 4xx 落到 ``MAPClientError``，未识别的 5xx 落到 ``MAPServerError``，
+  方便 CLI 兜底。
+"""
+
+
+class MAPError(Exception):
+    """Base SDK error."""
+
+
+class MAPHTTPError(MAPError):
+    """HTTP error from MAP API.
+
+    保留 ``status_code`` / ``detail`` 字段供调用方读取；具体子类对应
+    常见 HTTP 状态码，调用方可 catch 子类写语义化处理。
+
+    I1(d) 还携带三个可选的结构化字段（由 server 端 StateTransitionError
+    通过 exception handler 暴露）：
+
+    - ``error_code`` — stable machine identifier，便于调用方按错误类型
+      分支（例如 ``REVIEW_REJECT_RESULT_MISUSE`` 提示换用别的 CLI）。
+    - ``hint`` — 人类可读的修复提示，CLI 兜底展示。
+    - ``retryable`` — 是否值得用同样输入重试；misuse 子码恒为 ``False``。
+    """
+
+    def __init__(
+        self,
+        status_code: int,
+        detail: str,
+        *,
+        error_code: str | None = None,
+        hint: str | None = None,
+        retryable: bool | None = None,
+    ) -> None:
+        self.status_code = status_code
+        self.detail = detail
+        self.error_code = error_code
+        self.hint = hint
+        self.retryable = retryable
+        super().__init__(f"HTTP {status_code}: {detail}")
+
+
+class MAPClientError(MAPHTTPError):
+    """4xx client error (未细分子类的兜底）。"""
+
+
+class MAPServerError(MAPHTTPError):
+    """5xx server error."""
+
+
+class MAPValidationError(MAPClientError):
+    """400 / 422 — 请求参数校验失败或语义错误。"""
+
+
+class MAPAuthenticationError(MAPClientError):
+    """401 — 未认证或 token 失效。"""
+
+
+class MAPPermissionError(MAPClientError):
+    """403 — 已认证但无权限。"""
+
+
+class MAPNotFoundError(MAPClientError):
+    """404 — 资源不存在。"""
+
+
+class MAPConflictError(MAPClientError):
+    """409 — 状态冲突（重复提交、状态机非法转换等）。"""
+
+
+class MAPRateLimitError(MAPClientError):
+    """429 — 限流。"""
+
+
+# status_code → exception class 映射表。
+# 未列出的 4xx 落到 MAPClientError，5xx 落到 MAPServerError。
+_STATUS_CODE_MAP: dict[int, type[MAPHTTPError]] = {
+    400: MAPValidationError,
+    401: MAPAuthenticationError,
+    403: MAPPermissionError,
+    404: MAPNotFoundError,
+    409: MAPConflictError,
+    422: MAPValidationError,
+    429: MAPRateLimitError,
+}
+
+
+def raise_for_status(
+    status_code: int,
+    detail: str,
+    *,
+    error_code: str | None = None,
+    hint: str | None = None,
+    retryable: bool | None = None,
+) -> None:
+    """根据 status_code raise 对应的 MAPHTTPError 子类。
+
+    单一入口，供 ``MAPClient._request`` 在 ``status_code >= 400`` 时调用。
+    透传 server 端的结构化字段（I1(d) 起）：``error_code`` / ``hint`` /
+    ``retryable``，CLI 与调用方可以按 subcode 路由。
+    """
+    exc_cls = _STATUS_CODE_MAP.get(status_code)
+    if exc_cls is None:
+        exc_cls = MAPServerError if status_code >= 500 else MAPClientError
+    raise exc_cls(
+        status_code,
+        detail,
+        error_code=error_code,
+        hint=hint,
+        retryable=retryable,
+    )

map_client/plan_evidence.py

@@ -0,0 +1,159 @@
+"""8ac93d4e I1.a — Plan evidence_keys frontmatter parser.
+
+Extracts ``evidence_keys`` from YAML frontmatter in plan markdown so the
+CLI / SDK / server can validate that ``ExperimentLogCreate.metadata``
+covers every key the plan declared. Soft validation only — a missing
+key is a warning, never a block.
+
+Frontmatter format::
+
+    ---
+    evidence_keys:
+      - pytest_summary
+      - alembic_current
+      - api_health
+    ---
+
+Behavior contract (pinned by ``docs/MAP-EVIDENCE-METADATA.md``):
+
+* No frontmatter → ``PlanEvidenceKeys(keys=(), has_frontmatter=False)``.
+* Frontmatter without ``evidence_keys`` key → ``keys=(), has_frontmatter=True``.
+* Frontmatter with malformed YAML → raises :class:`PlanFrontmatterParseError`.
+* ``evidence_keys`` must be a list of non-empty strings; other shapes
+  (dict, scalar, list of non-strings) raise ``PlanFrontmatterParseError``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import yaml
+
+
+class PlanFrontmatterParseError(Exception):
+    """Raised when plan frontmatter YAML cannot be parsed.
+
+    Carries the raw frontmatter block + underlying YAML error so the
+    caller can render a friendly stderr warning without losing the
+    diagnostic detail.
+    """
+
+    def __init__(self, message: str, *, frontmatter: str | None = None) -> None:
+        super().__init__(message)
+        self.frontmatter = frontmatter
+
+
+@dataclass(frozen=True)
+class PlanEvidenceKeys:
+    """Result of parsing ``evidence_keys`` from plan markdown frontmatter."""
+
+    keys: tuple[str, ...]
+    has_frontmatter: bool
+    parse_error: str | None = None
+
+    def __bool__(self) -> bool:
+        return bool(self.keys)
+
+
+_FRONTMATTER_OPEN = "---"
+_LIST_TYPES = (list, tuple)
+
+
+def _split_frontmatter(plan_md: str) -> tuple[str | None, str]:
+    """Return ``(frontmatter_body_or_none, remainder)``.
+
+    Frontmatter is detected by the document starting with ``---\\n`` and
+    terminated by ``\\n---\\n`` / ``\\n---`` / ``---\\n`` at the start of
+    body / ``---`` at end-of-string. Returns ``(None, plan_md)`` when no
+    frontmatter is present.
+    """
+    if not plan_md.startswith(_FRONTMATTER_OPEN + "\n"):
+        return None, plan_md
+    body = plan_md[len(_FRONTMATTER_OPEN) + 1 :]
+    # Closing fence variants (in priority order):
+    # 1. ``\\n---\\n`` somewhere after the opening fence.
+    end_with_newline = body.find("\n" + _FRONTMATTER_OPEN + "\n", 3)
+    if end_with_newline != -1:
+        return (
+            body[:end_with_newline],
+            body[end_with_newline + len(_FRONTMATTER_OPEN) + 2 :],
+        )
+    # 2. ``---\\n`` at the very start of body (empty frontmatter case).
+    if body.startswith(_FRONTMATTER_OPEN + "\n"):
+        return "", body[len(_FRONTMATTER_OPEN) + 1 :]
+    # 3. ``---\\n`` at end-of-string with trailing newline.
+    if body.endswith(_FRONTMATTER_OPEN + "\n"):
+        return body[: -len(_FRONTMATTER_OPEN) - 1], ""
+    # 4. ``---`` at end-of-string without trailing newline.
+    if body.endswith(_FRONTMATTER_OPEN) and len(body) > len(_FRONTMATTER_OPEN):
+        return body[: -len(_FRONTMATTER_OPEN)], ""
+    return None, plan_md
+
+
+def _validate_evidence_keys_value(value: object) -> tuple[str, ...]:
+    """Coerce parsed YAML ``evidence_keys`` value into a tuple of strings.
+
+    Raises :class:`PlanFrontmatterParseError` for non-list shapes or
+    non-string / empty-string entries.
+    """
+    if not isinstance(value, _LIST_TYPES):
+        raise PlanFrontmatterParseError(
+            "evidence_keys must be a YAML list, got "
+            f"{type(value).__name__}"
+        )
+    keys: list[str] = []
+    for idx, item in enumerate(value):
+        if not isinstance(item, str):
+            raise PlanFrontmatterParseError(
+                f"evidence_keys[{idx}] must be a string, got "
+                f"{type(item).__name__}"
+            )
+        stripped = item.strip()
+        if not stripped:
+            raise PlanFrontmatterParseError(
+                f"evidence_keys[{idx}] must be non-empty"
+            )
+        keys.append(stripped)
+    # Dedupe while preserving order (first occurrence wins).
+    seen: set[str] = set()
+    deduped: list[str] = []
+    for key in keys:
+        if key not in seen:
+            seen.add(key)
+            deduped.append(key)
+    return tuple(deduped)
+
+
+def parse_plan_evidence_keys(plan_md: str) -> PlanEvidenceKeys:
+    """Extract ``evidence_keys`` from YAML frontmatter in plan markdown.
+
+    See module docstring for the full behavior contract.
+    """
+    frontmatter, _ = _split_frontmatter(plan_md)
+    if frontmatter is None:
+        return PlanEvidenceKeys(keys=(), has_frontmatter=False)
+
+    try:
+        parsed = yaml.safe_load(frontmatter)
+    except yaml.YAMLError as exc:
+        raise PlanFrontmatterParseError(
+            f"frontmatter YAML parse failed: {exc}",
+            frontmatter=frontmatter,
+        ) from exc
+
+    if parsed is None:
+        # Frontmatter present but empty.
+        return PlanEvidenceKeys(keys=(), has_frontmatter=True)
+
+    if not isinstance(parsed, dict):
+        raise PlanFrontmatterParseError(
+            "frontmatter top-level must be a YAML mapping, got "
+            f"{type(parsed).__name__}",
+            frontmatter=frontmatter,
+        )
+
+    if "evidence_keys" not in parsed:
+        return PlanEvidenceKeys(keys=(), has_frontmatter=True)
+
+    keys = _validate_evidence_keys_value(parsed["evidence_keys"])
+    return PlanEvidenceKeys(keys=keys, has_frontmatter=True)