openmd-cli 0.1.0__py3-none-any.whl

openmd/core/receipt.py

@@ -0,0 +1,285 @@
+"""Bounded, redacted receipts for opt-in compact CLI runs."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+from collections import Counter
+from pathlib import Path
+from typing import Any
+from uuid import uuid4
+
+
+_MAX_COUNT = (1 << 63) - 1
+_ERROR_CODES = frozenset(
+    {
+        "unknown",
+        "runtime_transient",
+        "source_unavailable",
+        "user_resolvable",
+        "code_resolvable",
+        "blocked",
+        "package_validation_failed",
+    }
+)
+
+
+class CompactReceiptRun:
+    TERMINAL_STATUSES = (
+        "verified",
+        "partial",
+        "terminal_gap",
+        "retryable_failure",
+        "blocked",
+        "failed",
+        "unattempted",
+    )
+
+    def __init__(self, out_dir: Path, run_dir: Path, run_id: str, command: str) -> None:
+        self.out_dir = out_dir
+        self.run_dir = run_dir
+        self.run_id = run_id
+        self.command = command
+        self.items_path = run_dir / "items.jsonl"
+        self.summary_path = run_dir / "summary.json"
+        self.checkpoint_path = run_dir / "checkpoint.json"
+        self._counts: Counter[str] = Counter()
+        self._errors: Counter[str] = Counter()
+        self._seen: set[str] = set()
+        self._occurrences = 0
+        self.expected: dict[str, int] = {}
+        self.requires_fresh_stdin = False
+
+    @classmethod
+    def create(cls, out_dir: str | Path, command: str) -> "CompactReceiptRun":
+        root = Path(out_dir)
+        run_id = uuid4().hex
+        run_dir = root / "runs" / run_id
+        run_dir.mkdir(parents=True, exist_ok=False)
+        run = cls(root, run_dir, run_id, command)
+        run.items_path.touch(exist_ok=False)
+        run.write_checkpoint()
+        return run
+
+    def has_item(self, identity: str) -> bool:
+        return identity in self._seen
+
+    @property
+    def has_items(self) -> bool:
+        return bool(self._seen)
+
+    def replace_expected(self, identities: dict[str, int]) -> None:
+        """Persist only redacted identities, never replayable input URLs."""
+        self.expected = dict(identities)
+        self._atomic_write_json(self.run_dir / "expected.json", self.expected)
+        self.write_checkpoint()
+
+    def add_occurrences(self, identity: str, occurrence: int) -> None:
+        """Reconcile a newly resolved alias against a completed item in this run."""
+        if identity not in self._seen:
+            return
+        rows, warnings = self.read_items_for_resume()
+        if warnings:
+            raise ValueError("cannot amend interrupted receipt")
+        for row in rows:
+            if row["stable_identity"] == identity:
+                row["input_occurrence"] += occurrence
+                break
+        self._atomic_write_text(
+            self.items_path,
+            "".join(json.dumps(row, ensure_ascii=False, separators=(",", ":")) + "\n" for row in rows),
+        )
+        self._occurrences += occurrence
+        self.write_checkpoint()
+
+    def write_checkpoint(self) -> None:
+        self._atomic_write_json(self.checkpoint_path, {
+            "schema_version": "openmd.compact-checkpoint.v1",
+            "run_id": self.run_id,
+            "completed": len(self._seen),
+            "expected_ref": "expected.json" if self.expected else None,
+            "expected_count": len(self.expected),
+            "requires_fresh_stdin": self.requires_fresh_stdin,
+        })
+
+    def record_item(
+        self,
+        *,
+        stable_identity: str,
+        input_occurrence: int,
+        status: str,
+        skipped: bool = False,
+        source_level: str | None = None,
+        quality_status: str | None = None,
+        error_code: str | None = None,
+        error_summary: str | None = None,
+        failure_class: str | None = None,
+        recovery_type: str | None = None,
+        artifact_ref: str | None = None,
+        route_trace: dict[str, Any] | None = None,
+    ) -> None:
+        if status not in self.TERMINAL_STATUSES:
+            raise ValueError(f"invalid terminal status: {status}")
+        if not stable_identity or stable_identity in self._seen:
+            raise ValueError("stable identity must be unique and non-empty")
+        if type(input_occurrence) is not int or input_occurrence < 1 or input_occurrence > _MAX_COUNT:
+            raise ValueError("input occurrence must be a positive integer")
+        normalized_error = self._normalize_error_code(error_code)
+        record = {
+            "stable_identity": stable_identity,
+            "input_occurrence": input_occurrence,
+            "status": status,
+            "skipped": skipped,
+            "artifact_ref": artifact_ref,
+            "source_level": source_level,
+            "quality_status": quality_status or "not_evaluated",
+            "error_code": normalized_error,
+            "failure_class": failure_class,
+            "recovery_type": recovery_type,
+        }
+        if route_trace:
+            record["route_trace"] = {key: route_trace[key] for key in ("card_id", "route_version", "overlay_applied") if key in route_trace}
+        # Error text may contain signed URLs, headers, or source content; never persist it.
+        del error_summary
+        with self.items_path.open("a", encoding="utf-8", newline="\n") as handle:
+            handle.write(json.dumps(record, ensure_ascii=False, separators=(",", ":")) + "\n")
+            handle.flush()
+            os.fsync(handle.fileno())
+        self._seen.add(stable_identity)
+        self._occurrences += input_occurrence
+        self._counts[status] += 1
+        if skipped:
+            self._counts["skipped"] += 1
+        if normalized_error:
+            self._errors[normalized_error] += 1
+        self.write_checkpoint()
+
+    def finalize(
+        self,
+        *,
+        discovery_complete: bool,
+        manifest_only: bool = False,
+        resume_supported: bool = False,
+        requires_fresh_stdin: bool = False,
+        limitations: list[str] | None = None,
+        failed: bool = False,
+    ) -> tuple[dict[str, Any], int]:
+        counts = {status: self._bounded_count(self._counts[status]) for status in self.TERMINAL_STATUSES}
+        counts["discovered"] = self._bounded_count(sum(counts.values()))
+        counts["skipped"] = self._bounded_count(self._counts["skipped"])
+        counts["input_occurrences"] = self._bounded_count(self._occurrences)
+        counts["duplicate_inputs"] = self._bounded_count(max(0, self._occurrences - counts["discovered"]))
+        accounting_complete = not self.expected or (
+            set(self.expected) == self._seen and sum(self.expected.values()) == self._occurrences
+        )
+        execution_complete = accounting_complete and counts["unattempted"] == 0
+        status = self._status_for(counts, discovery_complete=discovery_complete, manifest_only=manifest_only)
+        if failed or not accounting_complete:
+            status = "failed"
+        accessible = counts["discovered"] if discovery_complete and not any(
+            counts[state] for state in ("terminal_gap", "retryable_failure", "blocked", "failed", "unattempted")
+        ) else None
+        coverage = counts["verified"] / accessible if accessible else None
+        all_limitations = list(limitations or [])
+        if counts["discovered"] == 0 and "empty_scope" not in all_limitations:
+            all_limitations.append("empty_scope")
+        if requires_fresh_stdin and "requires_fresh_stdin" not in all_limitations:
+            all_limitations.append("requires_fresh_stdin")
+        summary = {
+            "schema_version": "openmd.run-summary.v1",
+            "run_id": self.run_id,
+            "command": self.command,
+            "status": status,
+            "counts": counts,
+            "discovery_complete": discovery_complete,
+            "accounting_complete": accounting_complete,
+            "execution_complete": execution_complete,
+            "coverage": coverage,
+            "accessible": accessible,
+            "resume_supported": resume_supported,
+            "items_ref": "items.jsonl",
+            "checkpoint_ref": "checkpoint.json",
+            "cost": {"external_calls": None, "metered_amount": None},
+            "limitations": all_limitations,
+        }
+        self.requires_fresh_stdin = requires_fresh_stdin
+        self.write_checkpoint()
+        self._atomic_write_json(self.summary_path, summary)
+        top_errors = sorted(self._errors.items(), key=lambda item: (-item[1], item[0]))
+        selected = dict(top_errors[:5])
+        other = sum(count for _, count in top_errors[5:])
+        summary_ref = self.summary_path.relative_to(self.out_dir).as_posix()
+        payload = {
+            "schema_version": "openmd.receipt.v1",
+            "status": status,
+            "counts": counts,
+            "summary_ref": summary_ref,
+            "error_counts": selected,
+            "other_error_count": other,
+        }
+        rendered = json.dumps(payload, ensure_ascii=False, separators=(",", ":")) + "\n"
+        if len(rendered.encode("utf-8")) > 2048:
+            raise ValueError("compact receipt exceeds 2048 UTF-8 bytes")
+        return payload, 0 if status in {"complete", "discovery_only"} else 1
+
+    def read_items_for_resume(self) -> tuple[list[dict[str, Any]], list[str]]:
+        raw = self.items_path.read_bytes()
+        lines = raw.splitlines(keepends=True)
+        rows: list[dict[str, Any]] = []
+        warnings: list[str] = []
+        for index, line in enumerate(lines):
+            final_line = index == len(lines) - 1
+            try:
+                rows.append(json.loads(line))
+            except (json.JSONDecodeError, UnicodeDecodeError) as exc:
+                if final_line and not line.endswith((b"\n", b"\r")):
+                    warnings.append("truncated_final_jsonl_line")
+                    break
+                raise ValueError("malformed_jsonl_line") from exc
+        return rows, warnings
+
+    @staticmethod
+    def stable_identity(*parts: str | None) -> str:
+        material = "\x1f".join(part or "" for part in parts)
+        return hashlib.sha256(material.encode("utf-8")).hexdigest()[:32]
+
+    @staticmethod
+    def _normalize_error_code(value: str | None) -> str | None:
+        if not value:
+            return None
+        normalized = str(value).lower()
+        return normalized if normalized in _ERROR_CODES else "unknown"
+
+    @staticmethod
+    def _bounded_count(value: int) -> int:
+        if type(value) is not int or value < 0 or value > _MAX_COUNT:
+            raise ValueError("receipt count is outside signed 64-bit range")
+        return value
+
+    @classmethod
+    def _atomic_write_json(cls, path: Path, payload: dict[str, Any]) -> None:
+        cls._atomic_write_text(path, json.dumps(payload, ensure_ascii=False, separators=(",", ":")))
+
+    @staticmethod
+    def _atomic_write_text(path: Path, text: str) -> None:
+        temporary = path.with_suffix(path.suffix + ".tmp")
+        with temporary.open("w", encoding="utf-8", newline="\n") as handle:
+            handle.write(text)
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(temporary, path)
+
+    @classmethod
+    def _status_for(cls, counts: dict[str, int], *, discovery_complete: bool, manifest_only: bool) -> str:
+        if counts["discovered"] == 0:
+            return "discovery_only" if manifest_only and discovery_complete else "blocked"
+        if manifest_only and discovery_complete:
+            return "discovery_only"
+        if counts["failed"] or counts["retryable_failure"]:
+            return "partial" if counts["verified"] or counts["partial"] else "failed"
+        if counts["blocked"] and not (counts["verified"] or counts["partial"]):
+            return "blocked"
+        if not discovery_complete or counts["partial"] or counts["terminal_gap"] or counts["unattempted"] or counts["blocked"]:
+            return "partial"
+        return "complete"

openmd/core/renderer.py

@@ -0,0 +1,185 @@
+"""Markdown rendering for normalized Openmd extraction results."""
+
+from __future__ import annotations
+
+import json
+import re
+from datetime import datetime, timezone
+from email.utils import parsedate_to_datetime
+from typing import Any
+
+from .models import ContentItem, MarkdownDocument, TranscriptResult
+from .readable import format_transcript, markdown_label
+from .secrets import sanitize_error_summary, sanitize_url_text
+
+
+FRONTMATTER_FIELDS: tuple[str, ...] = (
+    "title",
+    "author",
+    "url",
+    "published",
+    "platform",
+)
+
+_SOURCE_LABELS = {
+    "native_text": "原文",
+    "native_caption": "原生字幕",
+    "auto_caption": "自动字幕",
+    "platform_transcript": "平台逐字稿",
+    "third_party_extractor": "第三方提取",
+    "browser_rendered": "浏览器提取",
+    "manual_export": "手动导出",
+    "ocr": "文字识别",
+    "asr": "语音识别",
+    "media_asr": "语音识别",
+    "live_capture_asr": "实时语音识别",
+    "partial_extraction": "部分提取",
+}
+
+
+def utc_now_iso() -> str:
+    return datetime.now(timezone.utc).replace(microsecond=0).isoformat()
+
+
+def _frontmatter_value(value: Any) -> str:
+    if value is None or value == "":
+        return ""
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    text = str(value).replace("\r", " ").replace("\n", " ")
+    # JSON strings are valid YAML scalars and avoid implicit YAML booleans,
+    # numbers, dates and special punctuation in external titles/authors.
+    return json.dumps(text, ensure_ascii=False)
+
+
+def source_level_label(value: object) -> str:
+    return _SOURCE_LABELS.get(str(value), "提取文本")
+
+
+def published_date(value: object) -> str:
+    """Normalize known timestamp formats; unknown source labels stay intact."""
+    text = str(value or "").strip().replace("\r", " ").replace("\n", " ")
+    if not text:
+        return ""
+    try:
+        if re.fullmatch(r"\d{8}", text):
+            return datetime.strptime(text, "%Y%m%d").date().isoformat()
+        return datetime.fromisoformat(text.replace("Z", "+00:00")).date().isoformat()
+    except ValueError:
+        try:
+            return parsedate_to_datetime(text).date().isoformat()
+        except (TypeError, ValueError, OverflowError):
+            return text
+
+
+def build_source_notes(result: TranscriptResult) -> list[str]:
+    notes = [f"backend: {result.backend}", f"source_level: {result.source_level}"]
+    for note in result.source_notes:
+        if note:
+            notes.append(f"notes: {note}")
+    if result.error_code:
+        notes.append(f"error_code: {result.error_code}")
+    if result.error_summary:
+        summary = sanitize_error_summary(result.error_summary)
+        if summary:
+            notes.append(f"error_summary: {summary}")
+    return notes
+
+
+def render_markdown_document(
+    item: ContentItem,
+    result: TranscriptResult,
+    *,
+    captured_at: str | None = None,
+) -> MarkdownDocument:
+    title = result.title or item.title or item.id or "untitled"
+    image_post_author_text = (
+        item.platform == "douyin" and result.backend == "douyin.post-text"
+        and result.source_level == "native_text"
+        and result.metadata.get("transcript_method") == "image_post_text"
+        and result.metadata.get("media_kind") == "image_text"
+        and result.metadata.get("content_kind") == "author_text"
+    )
+    frontmatter = {
+        "platform": item.platform,
+        "url": sanitize_url_text(item.url),
+        "title": title,
+        "author": result.author or item.author,
+        "published_at": result.published_at or item.published_at,
+        "captured_at": captured_at or utc_now_iso(),
+        "source_type": "image_text" if image_post_author_text else item.source_type,
+        "image_post_author_text": image_post_author_text,
+        "status": result.status,
+        "source_level": result.source_level,
+        "backend": result.backend,
+    }
+    return MarkdownDocument(
+        frontmatter=frontmatter,
+        title=title,
+        content=result.text,
+        source_notes=build_source_notes(result),
+    )
+
+
+def _source_footer(document: MarkdownDocument) -> str:
+    level = str(document.frontmatter.get("source_level") or "")
+    label = "作者原文（图文）" if document.frontmatter.get("image_post_author_text") else source_level_label(level)
+    parts = ["来源：" + label]
+    if level in {"auto_caption", "ocr", "asr", "media_asr", "live_capture_asr"}:
+        parts.append("识别错误保持原样")
+    status = document.frontmatter.get("status")
+    if status == "partial":
+        parts.append("内容可能不完整")
+    elif status == "failed":
+        parts.append("提取失败")
+    if any("识别模型可能自动纠正原文错字" in note for note in document.source_notes):
+        parts.append("识别模型可能自动纠正原文错字")
+        parts.append("未触发回退不代表无幻觉")
+    # Keep user-relevant coverage warnings, not command traces or backend IDs.
+    if any("Single post only" in note for note in document.source_notes):
+        parts.append("仅此条帖子，未验证整串讨论覆盖")
+    if any("视频标题未取得" in note for note in document.source_notes):
+        parts.append("视频标题未取得")
+    elif any("视频作者未取得" in note for note in document.source_notes):
+        parts.append("视频作者未取得")
+    failed_images = sum(
+        note.startswith(("asset_download_failed:", "notes: asset_download_failed:"))
+        for note in document.source_notes
+    )
+    if failed_images:
+        parts.append(f"{failed_images} 张图片下载失败，保留远程链接")
+    return "*" + "；".join(parts) + "。*"
+
+
+def render_document(document: MarkdownDocument, *, raw: bool = False) -> str:
+    """Render a reading artifact; ``raw`` preserves the original body layout.
+
+    Structured extraction metadata remains on MarkdownDocument for runlogs and
+    package consumers; only the five human-facing source fields are printed.
+    """
+    lines = ["---"]
+    for field in FRONTMATTER_FIELDS:
+        value = document.frontmatter.get(field)
+        if field == "title":
+            value = document.title
+        if field == "published":
+            value = published_date(value or document.frontmatter.get("published_at"))
+        if value is None or (isinstance(value, str) and not value.strip()):
+            continue
+        lines.append(f"{field}: {_frontmatter_value(value)}")
+    content = document.content if raw or document.frontmatter.get("image_post_author_text") else format_transcript(
+        document.content,
+        source_type=document.frontmatter.get("source_type"),
+        platform=document.frontmatter.get("platform"),
+    )
+    heading = f"# {markdown_label(document.title)}"
+    if not raw and document.frontmatter.get("platform") != "x" and not document.frontmatter.get("image_post_author_text"):
+        # Source extractors may repeat a title as the first paragraph/heading.
+        # X post titles are derived from the body, so keep their first sentence.
+        # Promote only an exact match for sources with independent titles.
+        first, separator, rest = content.lstrip("\r\n").partition("\n")
+        if first.strip() in {document.title, "# " + document.title}:
+            content = rest.lstrip("\r\n") if separator else ""
+    prefix = "\n".join([*lines, "---", "", heading, "", ""])
+    # Do not rstrip raw content: trailing spaces/newlines can be meaningful.
+    return prefix + content + ("" if content.endswith("\n") else "\n") + "\n" + _source_footer(document) + "\n"

openmd/core/runlog.py

@@ -0,0 +1,208 @@
+"""Append-only lightweight runlog writer."""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from .models import ContentItem, FAILURE_CLASS_VALUES, TranscriptResult
+from .package_contract import extraction_contract_version_for
+from .secrets import asr_execution_metrics, sanitize_runlog_entry, sanitize_source_scope
+
+
+USER_RESOLVABLE_ERROR_TERMS: tuple[str, ...] = (
+    "auth",
+    "credential",
+    "login",
+    "permission",
+    "selector",
+    "target_scope",
+    "api_key_missing",
+    "session_expired",
+    "cache_stale",
+    "refresh_needed",
+    "export_required",
+    "target_missing",
+)
+SOURCE_UNAVAILABLE_ERROR_TERMS: tuple[str, ...] = (
+    "source_unavailable",
+    "source_empty",
+    "not_found",
+    "removed",
+    "deleted",
+    "empty_result",
+    "empty_content",
+    "no_transcript",
+    "subtitle_missing",
+    "no_delta",
+    "no_data",
+)
+RUNTIME_TRANSIENT_ERROR_TERMS: tuple[str, ...] = (
+    "timeout",
+    "rate_limit",
+    "locked",
+    "unreachable",
+    "temporarily",
+    "http_5",
+    "backend_exit",
+    "fetch_failed",
+)
+
+
+def utc_now_iso() -> str:
+    return datetime.now(timezone.utc).replace(microsecond=0).isoformat()
+
+
+def default_runlog_path(out_dir: str | Path) -> Path:
+    return Path(out_dir) / "runlog.jsonl"
+
+
+def append_runlog_entry(path: str | Path, entry: dict[str, Any]) -> dict[str, Any]:
+    runlog_path = Path(path)
+    runlog_path.parent.mkdir(parents=True, exist_ok=True)
+    sanitized = sanitize_runlog_entry(entry)
+    with runlog_path.open("a", encoding="utf-8", newline="\n") as file:
+        file.write(json.dumps(sanitized, ensure_ascii=False, sort_keys=True) + "\n")
+    return sanitized
+
+
+def build_runlog_entry(
+    *,
+    input_url: str,
+    platform: str,
+    backend: str,
+    status: str,
+    source_type: str,
+    source_level: str,
+    output_path: str | Path | None = None,
+    package_id: str | None = None,
+    package_operation: str | None = None,
+    started_at: str | None = None,
+    finished_at: str | None = None,
+    item_count: int = 1,
+    success_count: int | None = None,
+    failed_count: int | None = None,
+    event_type: str = "item",
+    failure_class: str | None = None,
+    guardrail_signals: list[str] | None = None,
+    resume_pointer: str | None = None,
+    error_code: str | None = None,
+    error_summary: str | None = None,
+    extraction_contract_version: str | None = None,
+    components: list[dict[str, Any]] | None = None,
+    terminal_gap_count: int = 0,
+    route_trace: dict[str, Any] | None = None,
+    document_metadata: dict[str, Any] | None = None,
+    asr_execution: dict[str, Any] | None = None,
+    source_scope: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    success = success_count if success_count is not None else int(status in {"verified", "partial"})
+    failed = failed_count if failed_count is not None else int(status == "failed")
+    normalized_failure_class = normalize_failure_class(failure_class) or classify_failure(error_code)
+    return {
+        "event_type": event_type,
+        "input_url": input_url,
+        "platform": platform,
+        "backend": backend,
+        "status": status,
+        "source_type": source_type,
+        "source_level": source_level,
+        "failure_class": normalized_failure_class,
+        "guardrail_signals": guardrail_signals or [],
+        "resume_pointer": resume_pointer,
+        "output_path": str(output_path) if output_path else "",
+        "package_id": package_id,
+        "package_operation": package_operation,
+        "started_at": started_at or utc_now_iso(),
+        "finished_at": finished_at or utc_now_iso(),
+        "item_count": item_count,
+        "success_count": success,
+        "failed_count": failed,
+        "error_code": error_code,
+        "error_summary": error_summary,
+        "extraction_contract_version": extraction_contract_version,
+        "components": components or [],
+        "terminal_gap_count": terminal_gap_count,
+        "route_trace": route_trace or {},
+        "document_metadata": document_metadata or {},
+        "asr_execution": asr_execution or {},
+        "source_scope": sanitize_source_scope(source_scope),
+    }
+
+
+def build_item_runlog_entry(
+    item: ContentItem,
+    result: TranscriptResult,
+    *,
+    output_path: str | Path | None = None,
+    package_id: str | None = None,
+    package_operation: str | None = None,
+    started_at: str | None = None,
+    finished_at: str | None = None,
+) -> dict[str, Any]:
+    failure_class = None
+    if isinstance(result.metadata, dict):
+        raw_failure_class = result.metadata.get("failure_class")
+        if isinstance(raw_failure_class, str):
+            failure_class = raw_failure_class
+    return build_runlog_entry(
+        input_url=item.url,
+        platform=item.platform,
+        backend=result.backend,
+        status=result.status,
+        source_type=item.source_type,
+        source_level=result.source_level,
+        asr_execution=asr_execution_metrics(result.metadata),
+        source_scope=result.metadata,
+        route_trace={key: result.metadata[key] for key in ("card_id", "route_version", "overlay_applied", "fallback_attempts") if key in result.metadata},
+        document_metadata={key: result.metadata[key] for key in ("pages", "office_loss_check", "office_recovery", "office_external_resources_fetched", "source_format", "mixed_routes", "pymupdf_version", "terminal_partial") if key in result.metadata} if item.platform in {"screenshot", "pdf"} else {},
+        output_path=output_path,
+        package_id=package_id,
+        package_operation=package_operation,
+        started_at=started_at,
+        finished_at=finished_at,
+        failure_class=failure_class,
+        error_code=result.error_code,
+        error_summary=result.error_summary,
+        extraction_contract_version=extraction_contract_version_for(item, result),
+        components=[
+            {
+                "id": component.id,
+                "kind": component.kind,
+                "status": component.status,
+                "source_level": component.source_level,
+                "backend": component.backend,
+                "text_ref": component.text_ref,
+                "warnings": component.warnings,
+                "terminal_reason": component.terminal_reason,
+                "error_code": component.error_code,
+                "failure_class": component.failure_class,
+            }
+            for component in result.normalized_components
+        ],
+        terminal_gap_count=sum(
+            component.status == "unavailable" for component in result.normalized_components
+        ),
+    )
+
+
+def normalize_failure_class(value: str | None) -> str | None:
+    if value in FAILURE_CLASS_VALUES:
+        return value
+    return None
+
+
+def classify_failure(error_code: str | None) -> str | None:
+    """Map backend-specific error codes into the shared V1 recovery taxonomy."""
+    if not error_code:
+        return None
+    normalized = str(error_code).lower()
+    if any(term in normalized for term in USER_RESOLVABLE_ERROR_TERMS):
+        return "user_resolvable"
+    if any(term in normalized for term in RUNTIME_TRANSIENT_ERROR_TERMS):
+        return "runtime_transient"
+    if any(term in normalized for term in SOURCE_UNAVAILABLE_ERROR_TERMS):
+        return "source_unavailable"
+    return "code_resolvable"