Add DMHY annotation workflow helpers

tools/annotate_dmhy_dag_agent.py

@@ -0,0 +1,1034 @@
+"""Run a small DAG-aware LLM annotation pass for DMHY filename suffixes.
+
+This runner is intentionally separate from the prefix-tree annotation scripts.
+It selects shared DAG suffix units, asks an OpenAI-compatible Responses API for
+strict JSON annotations, falls back to deterministic heuristics on failure, and
+emits both terminal patch rows and dmhy_weak-compatible sample records.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import time
+import urllib.error
+import urllib.request
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Iterable
+
+from anifilebert.tokenizer import AnimeTokenizer
+from tools.annotate_dmhy_prefix_graph import (
+    heuristic_patch,
+    normalize_generated_tokens,
+    string_list,
+    unique_keep_order,
+    write_jsonl,
+)
+from tools.dmhy_dataset import weak_label_filename
+
+
+DEFAULT_DAG = Path("datasets/AnimeName/dmhy_prefix_dag.json")
+DEFAULT_OUTPUT = Path("datasets/AnimeName/dmhy_weak.dag_sample.jsonl")
+DEFAULT_PATCH_OUTPUT = Path("datasets/AnimeName/dmhy_prefix_dag.annotations.dag_sample.jsonl")
+DEFAULT_UNITS_OUTPUT = Path("datasets/AnimeName/dmhy_prefix_dag.annotation_units.dag_sample.jsonl")
+DEFAULT_BASE_URL = "http://10.137.32.209/v1"
+DEFAULT_MODEL = "gpt-5.4-mini"
+LLM_SOURCE = "responses-dag-v1"
+HEURISTIC_SOURCE = "heuristic-dag-v1"
+COVERAGE_SHARED_ONLY = "shared-only"
+COVERAGE_ALL_TERMINALS = "all-terminals"
+
+
+@dataclass(frozen=True)
+class Args:
+    dag: Path
+    output: Path
+    patch_output: Path
+    units_output: Path | None
+    limit: int
+    max_requests: int
+    units_per_request: int
+    max_context_units: int
+    workers: int
+    coverage_mode: str
+    min_incoming_count: int
+    min_reachable_terminals: int
+    max_reachable_terminals: int | None
+    example_count: int
+    max_records: int
+    records_per_terminal: int
+    terminal_sink_threshold: int
+    terminal_cluster_size: int
+    llm: bool
+    base_url: str
+    api_key: str | None
+    model: str
+    http_timeout: int
+    retries: int
+    preserve_i_labels: bool
+    resume: bool
+
+
+def parse_args() -> Args:
+    parser = argparse.ArgumentParser(
+        description="Annotate a small sample of shared DMHY prefix-DAG suffix units"
+    )
+    parser.add_argument("--dag", type=Path, default=DEFAULT_DAG)
+    parser.add_argument("--output", type=Path, default=DEFAULT_OUTPUT)
+    parser.add_argument("--patch-output", type=Path, default=DEFAULT_PATCH_OUTPUT)
+    parser.add_argument(
+        "--units-output",
+        default=str(DEFAULT_UNITS_OUTPUT),
+        help="Optional selected annotation units JSONL; use empty string to disable",
+    )
+    parser.add_argument("--limit", type=int, default=20, help="Maximum DAG units to annotate")
+    parser.add_argument("--max-requests", type=int, default=20, help="Maximum LLM requests")
+    parser.add_argument("--units-per-request", type=int, default=10, help="DAG units per Responses API request")
+    parser.add_argument(
+        "--max-context-units",
+        type=int,
+        default=20,
+        help="Maximum unit contexts included in one Responses API request",
+    )
+    parser.add_argument("--workers", type=int, default=8, help="Concurrent LLM workers")
+    parser.add_argument(
+        "--coverage-mode",
+        choices=[COVERAGE_SHARED_ONLY, COVERAGE_ALL_TERMINALS],
+        default=COVERAGE_SHARED_ONLY,
+        help="Select only shared DAG units, or cover every terminal with terminal_cluster fallback units",
+    )
+    parser.add_argument("--min-incoming-count", type=int, default=2)
+    parser.add_argument("--min-reachable-terminals", type=int, default=2)
+    parser.add_argument(
+        "--max-reachable-terminals",
+        type=int,
+        default=500,
+        help="Skip very large shared units for sample runs; use 0 to disable",
+    )
+    parser.add_argument("--example-count", type=int, default=8)
+    parser.add_argument("--max-records", type=int, default=200, help="Maximum dataset records to emit")
+    parser.add_argument("--records-per-terminal", type=int, default=1)
+    parser.add_argument(
+        "--terminal-sink-threshold",
+        type=int,
+        default=1000,
+        help="Do not collect terminals from no-outgoing sink nodes above this size",
+    )
+    parser.add_argument(
+        "--terminal-cluster-size",
+        type=int,
+        default=1,
+        help="Number of uncovered terminals per all-terminals fallback cluster",
+    )
+    parser.add_argument("--llm", action="store_true", help="Use the Responses API; otherwise heuristics only")
+    parser.add_argument(
+        "--base-url",
+        default=os.environ.get("ANIFILEBERT_LLM_BASE_URL", DEFAULT_BASE_URL),
+        help="OpenAI-compatible API base URL",
+    )
+    parser.add_argument(
+        "--api-key",
+        default=os.environ.get("ANIFILEBERT_LLM_API_KEY"),
+        help="API key; defaults to ANIFILEBERT_LLM_API_KEY",
+    )
+    parser.add_argument("--model", default=DEFAULT_MODEL)
+    parser.add_argument("--http-timeout", type=int, default=120)
+    parser.add_argument("--retries", type=int, default=3)
+    parser.add_argument("--preserve-i-labels", action="store_true")
+    parser.add_argument("--resume", action="store_true", help="Skip ok/fallback unit_ids already in patch output")
+    ns = parser.parse_args()
+    units_arg = str(ns.units_output).strip()
+    return Args(
+        dag=ns.dag,
+        output=ns.output,
+        patch_output=ns.patch_output,
+        units_output=Path(units_arg) if units_arg else None,
+        limit=max(0, ns.limit),
+        max_requests=max(0, ns.max_requests),
+        units_per_request=max(1, ns.units_per_request),
+        max_context_units=max(1, ns.max_context_units),
+        workers=max(1, ns.workers),
+        coverage_mode=ns.coverage_mode,
+        min_incoming_count=max(1, ns.min_incoming_count),
+        min_reachable_terminals=max(1, ns.min_reachable_terminals),
+        max_reachable_terminals=None if ns.max_reachable_terminals <= 0 else ns.max_reachable_terminals,
+        example_count=max(1, ns.example_count),
+        max_records=max(0, ns.max_records),
+        records_per_terminal=max(1, ns.records_per_terminal),
+        terminal_sink_threshold=max(1, ns.terminal_sink_threshold),
+        terminal_cluster_size=max(1, ns.terminal_cluster_size),
+        llm=ns.llm,
+        base_url=ns.base_url,
+        api_key=ns.api_key,
+        model=ns.model,
+        http_timeout=max(1, ns.http_timeout),
+        retries=max(1, ns.retries),
+        preserve_i_labels=ns.preserve_i_labels,
+        resume=ns.resume,
+    )
+
+
+def load_dag(path: Path) -> dict[str, Any]:
+    if not path.exists():
+        raise SystemExit(f"DAG not found: {path}")
+    try:
+        dag = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise SystemExit(f"invalid DAG JSON in {path}: {exc}") from exc
+    if not isinstance(dag, dict) or not isinstance(dag.get("nodes"), list):
+        raise SystemExit(f"invalid DAG schema in {path}: missing nodes list")
+    if not isinstance(dag.get("terminals"), list):
+        raise SystemExit(f"invalid DAG schema in {path}: missing terminals list")
+    return dag
+
+
+def int_field(row: dict[str, Any], key: str, default: int = 0) -> int:
+    try:
+        return int(row.get(key, default) or default)
+    except (TypeError, ValueError):
+        return default
+
+
+def node_id(node: dict[str, Any], fallback: int) -> int:
+    try:
+        return int(node.get("id", fallback))
+    except (TypeError, ValueError):
+        raise SystemExit(f"invalid node id: {node.get('id')!r}") from None
+
+
+def terminal_id(terminal: dict[str, Any], fallback: int) -> str:
+    value = terminal.get("terminal_id", terminal.get("id", fallback))
+    return str(value)
+
+
+def has_outgoing_edges(node: dict[str, Any]) -> bool:
+    return any(isinstance(edge, dict) for edge in node.get("children") or [])
+
+
+def edge_labels(node: dict[str, Any], limit: int) -> list[str]:
+    labels: list[str] = []
+    for edge in node.get("children") or []:
+        if isinstance(edge, dict) and edge.get("label") is not None:
+            labels.append(str(edge["label"]))
+    return unique_keep_order(labels)[:limit]
+
+
+def build_indexes(
+    dag: dict[str, Any],
+) -> tuple[dict[int, dict[str, Any]], dict[int, list[dict[str, Any]]]]:
+    nodes: dict[int, dict[str, Any]] = {}
+    for index, node in enumerate(dag["nodes"]):
+        if isinstance(node, dict):
+            nodes[node_id(node, index)] = node
+
+    terminals_by_node: dict[int, list[dict[str, Any]]] = {}
+    for index, terminal in enumerate(dag["terminals"]):
+        if not isinstance(terminal, dict):
+            continue
+        try:
+            terminal_node_id = int(terminal.get("node_id"))
+        except (TypeError, ValueError):
+            continue
+        row = dict(terminal)
+        row["_terminal_id"] = terminal_id(row, index)
+        row["_terminal_index"] = index
+        terminals_by_node.setdefault(terminal_node_id, []).append(row)
+    return nodes, terminals_by_node
+
+
+class ReachableTerminals:
+    def __init__(
+        self,
+        nodes: dict[int, dict[str, Any]],
+        terminals_by_node: dict[int, list[dict[str, Any]]],
+        terminal_sink_threshold: int,
+    ) -> None:
+        self.nodes = nodes
+        self.terminals_by_node = terminals_by_node
+        self.terminal_sink_threshold = terminal_sink_threshold
+        self.memo: dict[int, list[dict[str, Any]]] = {}
+        self.visiting: set[int] = set()
+
+    def get(self, start: int) -> list[dict[str, Any]]:
+        if start in self.memo:
+            return self.memo[start]
+        if start in self.visiting:
+            raise SystemExit(f"cycle detected while traversing DAG at node {start}")
+        self.visiting.add(start)
+        node = self.nodes.get(start, {})
+        local_terminals = self.terminals_by_node.get(start, [])
+        is_large_terminal_sink = not has_outgoing_edges(node) and len(local_terminals) >= self.terminal_sink_threshold
+        found = [] if is_large_terminal_sink else list(local_terminals)
+        for edge in node.get("children") or []:
+            if not isinstance(edge, dict):
+                continue
+            try:
+                found.extend(self.get(int(edge.get("target"))))
+            except (TypeError, ValueError):
+                continue
+        self.visiting.remove(start)
+        deduped = dedupe_terminals(found)
+        self.memo[start] = deduped
+        return deduped
+
+
+def dedupe_terminals(terminals: Iterable[dict[str, Any]]) -> list[dict[str, Any]]:
+    seen: set[str] = set()
+    result: list[dict[str, Any]] = []
+    for terminal in terminals:
+        tid = str(terminal.get("_terminal_id") or terminal.get("terminal_id") or "")
+        if not tid or tid in seen:
+            continue
+        seen.add(tid)
+        result.append(terminal)
+    return result
+
+
+def aggregate_examples(terminals: Iterable[dict[str, Any]], key: str, limit: int) -> list[str]:
+    values: list[str] = []
+    for terminal in terminals:
+        if key == "prefix":
+            value = terminal.get("prefix")
+            if value is not None:
+                values.append(str(value))
+        else:
+            values.extend(string_list(terminal.get(key)))
+    return unique_keep_order(values)[:limit]
+
+
+def aggregate_terminal_field(terminals: Iterable[dict[str, Any]], key: str, limit: int) -> list[str]:
+    values: list[str] = []
+    for terminal in terminals:
+        value = terminal.get(key)
+        if value is not None:
+            values.append(str(value))
+    return unique_keep_order(values)[:limit]
+
+
+def heuristic_unit_patch(unit: dict[str, Any]) -> dict[str, Any]:
+    episode_titles: list[str] = []
+    media_suffixes: list[str] = []
+    title_candidates: list[str] = []
+    needs_review = False
+    for terminal in unit["_terminals"]:
+        patch = heuristic_patch(terminal, int(terminal.get("_terminal_index", 0)))
+        episode_titles.extend(patch["episode_title_suffixes"])
+        media_suffixes.extend(patch["media_suffixes"])
+        title_candidates.extend(patch["title_candidates"])
+        needs_review = needs_review or bool(patch["needs_llm_review"])
+    return {
+        "unit_id": unit["unit_id"],
+        "terminal_ids": unit["terminal_ids"],
+        "episode_title_suffixes": unique_keep_order(episode_titles),
+        "media_suffixes": unique_keep_order(media_suffixes),
+        "title_candidates": unique_keep_order(title_candidates),
+        "llm_label": None,
+        "notes": f"heuristic fallback; terminals={len(unit['terminal_ids'])}; needs_review={needs_review}",
+    }
+
+
+def make_unit(
+    node: dict[str, Any],
+    node_id_value: int,
+    terminals: list[dict[str, Any]],
+    example_count: int,
+) -> dict[str, Any]:
+    terminal_ids = [str(terminal["_terminal_id"]) for terminal in terminals]
+    reachable_weight = int_field(node, "reachable_weight")
+    if reachable_weight <= 0:
+        reachable_weight = sum(int_field(terminal, "weight", int_field(terminal, "count", 1)) for terminal in terminals)
+    return {
+        "unit_id": f"dag-node-{node_id_value}",
+        "node_id": node_id_value,
+        "kind": "shared_suffix",
+        "incoming_count": int_field(node, "incoming_count"),
+        "reachable_terminals": len(terminals),
+        "reachable_weight": reachable_weight,
+        "terminal_ids": terminal_ids,
+        "prefix_examples": aggregate_examples(terminals, "prefix", example_count),
+        "digit_skeleton_examples": aggregate_terminal_field(terminals, "digit_skeleton", example_count),
+        "value_examples": aggregate_examples(terminals, "value_examples", example_count),
+        "suffix_examples": aggregate_examples(terminals, "suffix_examples", example_count),
+        "common_edge_labels": edge_labels(node, example_count),
+        "_terminals": terminals,
+    }
+
+
+def make_terminal_cluster_unit(
+    terminals: list[dict[str, Any]],
+    cluster_index: int,
+    example_count: int,
+) -> dict[str, Any]:
+    terminal_ids = [str(terminal["_terminal_id"]) for terminal in terminals]
+    reachable_weight = sum(int_field(terminal, "weight", int_field(terminal, "count", 1)) for terminal in terminals)
+    return {
+        "unit_id": f"terminal-cluster-{cluster_index}",
+        "node_id": None,
+        "kind": "terminal_cluster",
+        "incoming_count": 0,
+        "reachable_terminals": len(terminals),
+        "reachable_weight": reachable_weight,
+        "terminal_ids": terminal_ids,
+        "prefix_examples": aggregate_examples(terminals, "prefix", example_count),
+        "digit_skeleton_examples": aggregate_terminal_field(terminals, "digit_skeleton", example_count),
+        "value_examples": aggregate_examples(terminals, "value_examples", example_count),
+        "suffix_examples": aggregate_examples(terminals, "suffix_examples", example_count),
+        "common_edge_labels": [],
+        "_terminals": terminals,
+    }
+
+
+def all_terminals(dag: dict[str, Any]) -> list[dict[str, Any]]:
+    terminals: list[dict[str, Any]] = []
+    for index, terminal in enumerate(dag["terminals"]):
+        if not isinstance(terminal, dict):
+            continue
+        row = dict(terminal)
+        row["_terminal_id"] = terminal_id(row, index)
+        row["_terminal_index"] = index
+        terminals.append(row)
+    return dedupe_terminals(terminals)
+
+
+def candidate_shared_units(
+    dag: dict[str, Any],
+    args: Args,
+) -> list[dict[str, Any]]:
+    nodes, terminals_by_node = build_indexes(dag)
+    reachable = ReachableTerminals(nodes, terminals_by_node, args.terminal_sink_threshold)
+    root = int(dag.get("root", 0) or 0)
+    candidates: list[tuple[tuple[int, int, int, int], int, dict[str, Any]]] = []
+    for current_id, node in nodes.items():
+        if current_id == root or not has_outgoing_edges(node):
+            continue
+        incoming_count = int_field(node, "incoming_count")
+        reachable_count = int_field(node, "reachable_terminals")
+        if incoming_count < args.min_incoming_count:
+            continue
+        if reachable_count < args.min_reachable_terminals:
+            continue
+        if args.max_reachable_terminals is not None and reachable_count > args.max_reachable_terminals:
+            continue
+        sort_key = (-incoming_count, -int_field(node, "reachable_weight"), -reachable_count, current_id)
+        candidates.append((sort_key, current_id, node))
+
+    candidates.sort(key=lambda item: item[0])
+    candidates.sort(key=lambda item: item[0])
+    units: list[dict[str, Any]] = []
+    for _sort_key, current_id, node in candidates:
+        terminals = reachable.get(current_id)
+        if not terminals:
+            continue
+        units.append(make_unit(node, current_id, terminals, args.example_count))
+    return units
+
+
+def unique_terminal_coverage(units: Iterable[dict[str, Any]]) -> set[str]:
+    covered: set[str] = set()
+    for unit in units:
+        covered.update(str(terminal_id_value) for terminal_id_value in unit.get("terminal_ids") or [])
+    return covered
+
+
+def shared_only_units(dag: dict[str, Any], args: Args) -> list[dict[str, Any]]:
+    limit = args.limit if args.limit > 0 else 0
+    return candidate_shared_units(dag, args)[:limit]
+
+
+def all_terminal_units(dag: dict[str, Any], args: Args) -> list[dict[str, Any]]:
+    terminals = all_terminals(dag)
+    terminals_by_id = {str(terminal["_terminal_id"]): terminal for terminal in terminals}
+    selected: list[dict[str, Any]] = []
+    covered: set[str] = set()
+
+    for unit in candidate_shared_units(dag, args):
+        unit_terminal_ids = set(unit["terminal_ids"])
+        if not unit_terminal_ids:
+            continue
+        if unit_terminal_ids & covered:
+            continue
+        selected.append(unit)
+        covered.update(unit_terminal_ids)
+
+    uncovered = [terminal for terminal in terminals if str(terminal["_terminal_id"]) not in covered]
+    for start in range(0, len(uncovered), args.terminal_cluster_size):
+        cluster_terminals = uncovered[start : start + args.terminal_cluster_size]
+        selected.append(
+            make_terminal_cluster_unit(
+                cluster_terminals,
+                cluster_index=(start // args.terminal_cluster_size) + 1,
+                example_count=args.example_count,
+            )
+        )
+        covered.update(str(terminal["_terminal_id"]) for terminal in cluster_terminals)
+
+    expected_ids = set(terminals_by_id)
+    if covered != expected_ids:
+        missing = sorted(expected_ids - covered)[:10]
+        extra = sorted(covered - expected_ids)[:10]
+        raise SystemExit(
+            "all-terminals coverage mismatch: "
+            f"expected={len(expected_ids)} covered={len(covered)} missing={missing} extra={extra}"
+        )
+    return selected
+
+
+def select_units(dag: dict[str, Any], args: Args) -> list[dict[str, Any]]:
+    if args.coverage_mode == COVERAGE_ALL_TERMINALS:
+        return all_terminal_units(dag, args)
+    return shared_only_units(dag, args)
+
+
+def annotation_schema() -> dict[str, Any]:
+    return {
+        "type": "object",
+        "additionalProperties": False,
+        "required": [
+            "unit_id",
+            "terminal_ids",
+            "episode_title_suffixes",
+            "media_suffixes",
+            "title_candidates",
+            "llm_label",
+            "notes",
+        ],
+        "properties": {
+            "unit_id": {"type": "string"},
+            "terminal_ids": {"type": "array", "items": {"type": "string"}},
+            "episode_title_suffixes": {"type": "array", "items": {"type": "string"}},
+            "media_suffixes": {"type": "array", "items": {"type": "string"}},
+            "title_candidates": {"type": "array", "items": {"type": "string"}},
+            "llm_label": {"type": ["string", "null"]},
+            "notes": {"type": "string"},
+        },
+    }
+
+
+def batch_annotation_schema() -> dict[str, Any]:
+    return {
+        "type": "object",
+        "additionalProperties": False,
+        "required": ["annotations"],
+        "properties": {
+            "annotations": {
+                "type": "array",
+                "items": annotation_schema(),
+            }
+        },
+    }
+
+
+def responses_url(base_url: str) -> str:
+    return base_url.rstrip("/") + "/responses"
+
+
+def unit_request_context(unit: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "unit_id": unit["unit_id"],
+        "node_id": unit["node_id"],
+        "terminal_ids": unit["terminal_ids"],
+        "incoming_count": unit["incoming_count"],
+        "reachable_terminals": unit["reachable_terminals"],
+        "reachable_weight": unit["reachable_weight"],
+        "prefix_examples": unit["prefix_examples"],
+        "value_examples": unit["value_examples"],
+        "suffix_examples": unit["suffix_examples"],
+        "common_edge_labels": unit["common_edge_labels"],
+        "heuristic_patch": heuristic_unit_patch(unit),
+    }
+
+
+def request_variants(units: list[dict[str, Any]], args: Args, previous_error: str | None = None) -> list[dict[str, Any]]:
+    if not units:
+        raise ValueError("request_variants requires at least one unit")
+    instructions = (
+        "You annotate anime release filename DAG suffix units. Classify only suffix text that is "
+        "a human episode title into episode_title_suffixes. Put resolution, codec, source, audio, "
+        "subtitle, language, hash, release, and file-format fragments into media_suffixes. "
+        "Use title_candidates for possible anime title strings found in prefix/value examples. Return "
+        "strict JSON matching the supplied schema with one annotation per input unit. Keep unit_id and "
+        "terminal_ids exactly unchanged for every unit."
+    )
+    if previous_error:
+        instructions += f" Previous attempt failed validation: {previous_error}. Correct only that issue."
+    input_obj = {
+        "units": [unit_request_context(unit) for unit in units[: args.max_context_units]],
+    }
+    schema = batch_annotation_schema()
+    base = {
+        "model": args.model,
+        "instructions": instructions,
+        "input": json.dumps(input_obj, ensure_ascii=False),
+    }
+    return [
+        {
+            **base,
+            "reasoning": {"effort": "medium"},
+            "text": {
+                "format": {
+                    "type": "json_schema",
+                    "name": "dmhy_dag_batch_annotation",
+                    "strict": True,
+                    "schema": schema,
+                }
+            },
+        },
+        {
+            **base,
+            "text": {
+                "format": {
+                    "type": "json_schema",
+                    "name": "dmhy_dag_batch_annotation",
+                    "strict": True,
+                    "schema": schema,
+                }
+            },
+        },
+        {
+            **base,
+            "tools": [
+                {
+                    "type": "function",
+                    "name": "submit_dmhy_dag_batch_annotation",
+                    "strict": True,
+                    "parameters": schema,
+                    "description": "Submit strict DMHY DAG suffix annotations for all input units.",
+                }
+            ],
+            "tool_choice": {"type": "function", "name": "submit_dmhy_dag_batch_annotation"},
+        },
+    ]
+
+
+def http_post_json(payload: dict[str, Any], args: Args) -> dict[str, Any]:
+    if not args.api_key:
+        raise RuntimeError("--llm requires --api-key or ANIFILEBERT_LLM_API_KEY")
+    request = urllib.request.Request(
+        responses_url(args.base_url),
+        data=json.dumps(payload, ensure_ascii=False).encode("utf-8"),
+        headers={
+            "Authorization": f"Bearer {args.api_key}",
+            "Content-Type": "application/json",
+        },
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=args.http_timeout) as response:
+            raw = response.read().decode("utf-8")
+    except urllib.error.HTTPError as exc:
+        body = exc.read().decode("utf-8", errors="replace")
+        raise RuntimeError(f"Responses API HTTP {exc.code}: {body[:500]}") from exc
+    except (urllib.error.URLError, OSError) as exc:
+        raise RuntimeError(f"Responses API request failed: {exc}") from exc
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise RuntimeError(f"Responses API returned invalid JSON envelope: {raw[:500]}") from exc
+    if not isinstance(data, dict):
+        raise RuntimeError("Responses API envelope must be a JSON object")
+    return data
+
+
+def extract_annotation_payload(data: dict[str, Any]) -> dict[str, Any]:
+    output_text = data.get("output_text")
+    if isinstance(output_text, str) and output_text.strip():
+        return json.loads(strip_json_fence(output_text))
+
+    text_chunks: list[str] = []
+    for item in data.get("output") or []:
+        if not isinstance(item, dict):
+            continue
+        if item.get("type") in {"function_call", "tool_call"}:
+            arguments = item.get("arguments")
+            if isinstance(arguments, str) and arguments.strip():
+                return json.loads(arguments)
+            if isinstance(arguments, dict):
+                return arguments
+        for content in item.get("content") or []:
+            if not isinstance(content, dict):
+                continue
+            text = content.get("text")
+            if isinstance(text, str):
+                text_chunks.append(text)
+            if content.get("type") in {"function_call", "tool_call"}:
+                arguments = content.get("arguments")
+                if isinstance(arguments, str) and arguments.strip():
+                    return json.loads(arguments)
+                if isinstance(arguments, dict):
+                    return arguments
+    if text_chunks:
+        return json.loads(strip_json_fence("\n".join(text_chunks)))
+    raise RuntimeError("Responses API did not include annotation text or tool arguments")
+
+
+def strip_json_fence(text: str) -> str:
+    text = text.strip()
+    if text.startswith("```"):
+        lines = text.splitlines()
+        if lines:
+            lines = lines[1:]
+        if lines and lines[-1].strip() == "```":
+            lines = lines[:-1]
+        return "\n".join(lines).strip()
+    return text
+
+
+def validate_annotation(annotation: Any, unit: dict[str, Any]) -> dict[str, Any]:
+    if not isinstance(annotation, dict):
+        raise RuntimeError("annotation must be a JSON object")
+    missing = [key for key in annotation_schema()["required"] if key not in annotation]
+    if missing:
+        raise RuntimeError(f"annotation missing required keys: {', '.join(missing)}")
+    if annotation["unit_id"] != unit["unit_id"]:
+        raise RuntimeError(f"unit_id mismatch: {annotation['unit_id']!r}")
+    returned_ids = [str(item) for item in annotation.get("terminal_ids") or []]
+    if returned_ids != unit["terminal_ids"]:
+        raise RuntimeError("terminal_ids mismatch")
+    cleaned = {
+        "unit_id": unit["unit_id"],
+        "terminal_ids": unit["terminal_ids"],
+        "episode_title_suffixes": unique_keep_order(str(item) for item in annotation["episode_title_suffixes"]),
+        "media_suffixes": unique_keep_order(str(item) for item in annotation["media_suffixes"]),
+        "title_candidates": unique_keep_order(str(item) for item in annotation["title_candidates"]),
+        "llm_label": annotation["llm_label"] if annotation["llm_label"] is None else str(annotation["llm_label"]),
+        "notes": str(annotation["notes"]),
+    }
+    return cleaned
+
+
+def validate_batch_annotation(payload: Any, units: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    if not isinstance(payload, dict):
+        raise RuntimeError("batch annotation must be a JSON object")
+    annotations = payload.get("annotations")
+    if not isinstance(annotations, list):
+        raise RuntimeError("batch annotation missing annotations list")
+    expected_ids = [unit["unit_id"] for unit in units]
+    returned_ids = [
+        str(annotation.get("unit_id"))
+        for annotation in annotations
+        if isinstance(annotation, dict) and annotation.get("unit_id") is not None
+    ]
+    if sorted(returned_ids) != sorted(expected_ids) or len(returned_ids) != len(expected_ids):
+        raise RuntimeError(f"unit_id set mismatch: expected={expected_ids!r} returned={returned_ids!r}")
+    annotations_by_id: dict[str, Any] = {}
+    for annotation in annotations:
+        if not isinstance(annotation, dict):
+            raise RuntimeError("annotations entries must be JSON objects")
+        unit_id_value = str(annotation.get("unit_id"))
+        if unit_id_value in annotations_by_id:
+            raise RuntimeError(f"duplicate annotation unit_id: {unit_id_value}")
+        annotations_by_id[unit_id_value] = annotation
+    cleaned: list[dict[str, Any]] = []
+    for unit in units:
+        cleaned.append(validate_annotation(annotations_by_id[unit["unit_id"]], unit))
+    return cleaned
+
+
+def annotate_batch(units: list[dict[str, Any]], args: Args, use_llm: bool) -> list[dict[str, Any]]:
+    if not use_llm:
+        patches: list[dict[str, Any]] = []
+        for unit in units:
+            patch = heuristic_unit_patch(unit)
+            patch.update({"source": HEURISTIC_SOURCE, "fallback": True, "attempts": 0, "errors": []})
+            patches.append(patch)
+        return patches
+
+    errors: list[str] = []
+    for attempt in range(args.retries):
+        variants = request_variants(units, args, errors[-1] if errors else None)
+        payload = variants[min(attempt, len(variants) - 1)]
+        try:
+            data = http_post_json(payload, args)
+            annotations = validate_batch_annotation(extract_annotation_payload(data), units)
+            for annotation in annotations:
+                annotation.update({"source": LLM_SOURCE, "fallback": False, "attempts": attempt + 1, "errors": []})
+            return annotations
+        except (RuntimeError, json.JSONDecodeError, TypeError, ValueError) as exc:
+            errors.append(str(exc))
+            time.sleep(min(2.0, 0.25 * (attempt + 1)))
+
+    patches = []
+    for unit in units:
+        patch = heuristic_unit_patch(unit)
+        patch.update(
+            {
+                "source": HEURISTIC_SOURCE,
+                "fallback": True,
+                "attempts": args.retries,
+                "errors": errors[-3:],
+                "notes": f"{patch['notes']}; llm_failed_after={args.retries}",
+            }
+        )
+        patches.append(patch)
+    return patches
+
+
+def annotate_unit(unit: dict[str, Any], args: Args, use_llm: bool) -> dict[str, Any]:
+    return annotate_batch([unit], args, use_llm)[0]
+
+
+def chunk_units(units: list[dict[str, Any]], size: int) -> list[list[dict[str, Any]]]:
+    return [units[index : index + size] for index in range(0, len(units), size)]
+
+
+def load_resume_patches(path: Path) -> dict[str, dict[str, Any]]:
+    if not path.exists():
+        return {}
+    completed: dict[str, dict[str, Any]] = {}
+    for line_number, line in enumerate(path.read_text(encoding="utf-8").splitlines(), 1):
+        if not line.strip():
+            continue
+        try:
+            row = json.loads(line)
+        except json.JSONDecodeError as exc:
+            raise SystemExit(f"invalid resume patch JSON in {path}:{line_number}: {exc}") from exc
+        if not isinstance(row, dict):
+            continue
+        unit_id_value = row.get("unit_id")
+        if not unit_id_value:
+            continue
+        status = row.get("status")
+        is_legacy_completed = status is None and ("source" in row or "fallback" in row)
+        is_completed = status in {"ok", "fallback"} or is_legacy_completed
+        if is_completed:
+            completed[str(unit_id_value)] = row
+    return completed
+
+
+def patch_from_resume_row(unit: dict[str, Any], row: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "unit_id": unit["unit_id"],
+        "terminal_ids": unit["terminal_ids"],
+        "episode_title_suffixes": unique_keep_order(str(item) for item in row.get("episode_title_suffixes") or []),
+        "media_suffixes": unique_keep_order(str(item) for item in row.get("media_suffixes") or []),
+        "title_candidates": unique_keep_order(str(item) for item in row.get("title_candidates") or []),
+        "llm_label": row.get("llm_label"),
+        "notes": str(row.get("notes", "")),
+        "source": str(row.get("source") or HEURISTIC_SOURCE),
+        "fallback": bool(row.get("fallback", row.get("status") == "fallback")),
+        "attempts": int_field(row, "attempts"),
+        "errors": list(row.get("errors") or []),
+    }
+
+
+def patch_row(unit: dict[str, Any], patch: dict[str, Any]) -> dict[str, Any]:
+    fallback = bool(patch["fallback"])
+    return {
+        "unit_id": unit["unit_id"],
+        "node_id": unit["node_id"],
+        "kind": unit["kind"],
+        "incoming_count": unit["incoming_count"],
+        "reachable_terminals": unit["reachable_terminals"],
+        "reachable_weight": unit["reachable_weight"],
+        "terminal_ids": patch["terminal_ids"],
+        "episode_title_suffixes": patch["episode_title_suffixes"],
+        "media_suffixes": patch["media_suffixes"],
+        "title_candidates": patch["title_candidates"],
+        "llm_label": patch["llm_label"],
+        "notes": patch["notes"],
+        "source": patch["source"],
+        "fallback": fallback,
+        "status": "fallback" if fallback else "ok",
+        "attempts": patch["attempts"],
+        "errors": patch["errors"],
+        "annotated_at": datetime.now(timezone.utc).isoformat(),
+    }
+
+
+def unit_source_id(unit: dict[str, Any]) -> str:
+    node_id_value = unit.get("node_id")
+    if node_id_value is None:
+        return str(unit["unit_id"])
+    return str(node_id_value)
+
+
+def unit_public_row(unit: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "unit_id": unit["unit_id"],
+        "source_kind": "prefix_dag",
+        "source_id": unit_source_id(unit),
+        "terminal_ids": unit["terminal_ids"],
+        "weight": int(unit["reachable_weight"]),
+        "context": {
+            "prefixes": unit["prefix_examples"],
+            "digit_skeletons": unit["digit_skeleton_examples"],
+            "edge_labels": unit["common_edge_labels"],
+            "notes": (
+                f"kind={unit['kind']}; incoming_count={unit['incoming_count']}; "
+                f"reachable_terminals={unit['reachable_terminals']}"
+            ),
+        },
+        "examples": {
+            "values": unit["value_examples"],
+            "suffixes": unit["suffix_examples"],
+        },
+        "expected_output": {
+            "schema_version": "dmhy-annotation-v1",
+        },
+    }
+
+
+def dataset_records(
+    units: list[dict[str, Any]],
+    patches: list[dict[str, Any]],
+    args: Args,
+) -> list[dict[str, Any]]:
+    tokenizer = AnimeTokenizer()
+    records: list[dict[str, Any]] = []
+    seen: set[str] = set()
+    for unit, patch in zip(units, patches):
+        per_terminal_counts: dict[str, int] = {}
+        for terminal in unit["_terminals"]:
+            terminal_id_value = str(terminal["_terminal_id"])
+            for source_index, filename in enumerate(string_list(terminal.get("value_examples"))):
+                if len(records) >= args.max_records:
+                    return records
+                if per_terminal_counts.get(terminal_id_value, 0) >= args.records_per_terminal:
+                    break
+                if filename in seen:
+                    continue
+                seen.add(filename)
+                sample = weak_label_filename(filename, tokenizer)
+                if sample is None:
+                    continue
+                tokens, labels = normalize_generated_tokens(
+                    sample["tokens"],
+                    sample["labels"],
+                    preserve_i_labels=args.preserve_i_labels,
+                )
+                records.append(
+                    {
+                        "file_id": f"prefix-dag:{unit['unit_id']}:{terminal_id_value}:{source_index}",
+                        "filename": filename,
+                        "tokens": tokens,
+                        "labels": labels,
+                        "terminal_id": terminal_id_value,
+                        "terminal_index": terminal["_terminal_index"],
+                        "unit_id": unit["unit_id"],
+                        "source": patch["source"],
+                        "needs_llm_review": patch["fallback"],
+                        "episode_title_suffixes": patch["episode_title_suffixes"],
+                        "media_suffixes": patch["media_suffixes"],
+                        "title_candidates": patch["title_candidates"],
+                        "annotations": {
+                            "unit_id": unit["unit_id"],
+                            "terminal_id": terminal_id_value,
+                            "terminal_index": terminal["_terminal_index"],
+                            "source": patch["source"],
+                            "fallback": patch["fallback"],
+                            "episode_title_suffixes": patch["episode_title_suffixes"],
+                            "media_suffixes": patch["media_suffixes"],
+                            "title_candidates": patch["title_candidates"],
+                            "llm_label": patch["llm_label"],
+                            "notes": patch["notes"],
+                        },
+                    }
+                )
+                per_terminal_counts[terminal_id_value] = per_terminal_counts.get(terminal_id_value, 0) + 1
+    return records
+
+
+def annotate_units(
+    units: list[dict[str, Any]],
+    args: Args,
+) -> tuple[list[tuple[dict[str, Any], dict[str, Any]]], int, int, int]:
+    resume_rows = load_resume_patches(args.patch_output) if args.resume else {}
+    results: list[dict[str, Any] | None] = [None] * len(units)
+    pending: list[tuple[int, dict[str, Any]]] = []
+    skipped = 0
+    for index, unit in enumerate(units):
+        row = resume_rows.get(unit["unit_id"])
+        if row is not None and [str(item) for item in row.get("terminal_ids") or []] == unit["terminal_ids"]:
+            results[index] = patch_from_resume_row(unit, row)
+            skipped += 1
+        else:
+            pending.append((index, unit))
+
+    batch_size = max(1, min(args.units_per_request, args.max_context_units))
+    batches = [
+        ([index for index, _unit in batch], [unit for _index, unit in batch])
+        for batch in chunk_units(pending, batch_size)
+    ]
+    if args.llm:
+        runnable_batches = batches[: args.max_requests]
+        llm_requested = len(runnable_batches)
+    else:
+        runnable_batches = batches
+        llm_requested = 0
+    with ThreadPoolExecutor(max_workers=args.workers) as executor:
+        futures = {
+            executor.submit(annotate_batch, batch_units, args, args.llm): indices
+            for indices, batch_units in runnable_batches
+        }
+        for future in as_completed(futures):
+            indices = futures[future]
+            for index, patch in zip(indices, future.result()):
+                results[index] = patch
+    completed = [
+        (unit, patch)
+        for unit, patch in zip(units, results)
+        if patch is not None
+    ]
+    pending_unprocessed = len(units) - len(completed)
+    return completed, skipped, llm_requested, pending_unprocessed
+
+
+def main() -> None:
+    args = parse_args()
+    if args.llm and not args.api_key:
+        raise SystemExit("--llm requires --api-key or ANIFILEBERT_LLM_API_KEY")
+
+    dag = load_dag(args.dag)
+    units = select_units(dag, args)
+    if not units:
+        raise SystemExit("no DAG units selected; adjust --limit/--min-incoming-count")
+
+    completed_pairs, resume_skipped, llm_requested, pending_unprocessed = annotate_units(units, args)
+    completed_units = [unit for unit, _patch in completed_pairs]
+    patches = [patch for _unit, patch in completed_pairs]
+    patch_rows = [patch_row(unit, patch) for unit, patch in completed_pairs]
+    records = dataset_records(completed_units, patches, args)
+
+    patch_count = write_jsonl(args.patch_output, patch_rows)
+    record_count = write_jsonl(args.output, records)
+    unit_count = 0
+    if args.units_output is not None:
+        unit_count = write_jsonl(args.units_output, (unit_public_row(unit) for unit in units))
+
+    fallback_count = sum(1 for patch in patches if patch["fallback"])
+    terminal_count = len(all_terminals(dag))
+    unique_coverage_count = len(unique_terminal_coverage(units))
+    summary = {
+        "dag": str(args.dag),
+        "coverage_mode": args.coverage_mode,
+        "units_output": str(args.units_output) if args.units_output is not None else None,
+        "patch_output": str(args.patch_output),
+        "output": str(args.output),
+        "selected_units": len(units),
+        "dag_terminals": terminal_count,
+        "unique_terminal_coverage": unique_coverage_count,
+        "written_units": unit_count,
+        "written_patches": patch_count,
+        "written_records": record_count,
+        "llm_requested": llm_requested,
+        "pending_unprocessed": pending_unprocessed,
+        "units_per_request": args.units_per_request,
+        "max_context_units": args.max_context_units,
+        "resume": args.resume,
+        "resume_skipped": resume_skipped,
+        "fallback_count": fallback_count,
+        "workers": args.workers,
+        "model": args.model if args.llm else None,
+    }
+    print(json.dumps(summary, ensure_ascii=False, indent=2))
+    if fallback_count:
+        print(f"warning: {fallback_count} unit(s) used heuristic fallback", file=sys.stderr)
+
+
+if __name__ == "__main__":
+    main()

tools/annotate_dmhy_prefix_dag.py

@@ -31,6 +31,7 @@ class Args:
     min_incoming_count: int
     limit: int | None
     example_count: int
+    include_terminal_sink_units: bool
 
 
 def parse_args() -> Args:
@@ -63,6 +64,11 @@ def parse_args() -> Args:
         default=5,
         help="Maximum examples retained per example field",
     )
+    parser.add_argument(
+        "--include-terminal-sink-units",
+        action="store_true",
+        help="Include terminal nodes with no outgoing edges as annotation units",
+    )
     ns = parser.parse_args()
     return Args(
         dag=ns.dag,
@@ -71,6 +77,7 @@ def parse_args() -> Args:
         min_incoming_count=max(1, ns.min_incoming_count),
         limit=ns.limit,
         example_count=max(1, ns.example_count),
+        include_terminal_sink_units=ns.include_terminal_sink_units,
     )
 
 
@@ -132,22 +139,25 @@ def build_indexes(dag: dict[str, Any]) -> tuple[dict[int, dict[str, Any]], dict[
     return nodes, terminals_by_node
 
 
-def reachable_terminals(
-    start_node_id: int,
-    nodes: dict[int, dict[str, Any]],
-    terminals_by_node: dict[int, list[dict[str, Any]]],
-) -> list[dict[str, Any]]:
-    memo: dict[int, list[dict[str, Any]]] = {}
-    visiting: set[int] = set()
-
-    def visit(current_id: int) -> list[dict[str, Any]]:
-        if current_id in memo:
-            return memo[current_id]
-        if current_id in visiting:
-            raise SystemExit(f"cycle detected while traversing DAG at node {current_id}")
-        visiting.add(current_id)
-        found = list(terminals_by_node.get(current_id, []))
-        node = nodes.get(current_id, {})
+class ReachableTerminalIndex:
+    def __init__(
+        self,
+        nodes: dict[int, dict[str, Any]],
+        terminals_by_node: dict[int, list[dict[str, Any]]],
+    ) -> None:
+        self.nodes = nodes
+        self.terminals_by_node = terminals_by_node
+        self.memo: dict[int, list[dict[str, Any]]] = {}
+        self.visiting: set[int] = set()
+
+    def get(self, start_node_id: int) -> list[dict[str, Any]]:
+        if start_node_id in self.memo:
+            return self.memo[start_node_id]
+        if start_node_id in self.visiting:
+            raise SystemExit(f"cycle detected while traversing DAG at node {start_node_id}")
+        self.visiting.add(start_node_id)
+        found = list(self.terminals_by_node.get(start_node_id, []))
+        node = self.nodes.get(start_node_id, {})
         for edge in node.get("children") or []:
             if not isinstance(edge, dict):
                 continue
@@ -155,14 +165,12 @@ def reachable_terminals(
                 target = int(edge.get("target"))
             except (TypeError, ValueError):
                 continue
-            found.extend(visit(target))
-        visiting.remove(current_id)
+            found.extend(self.get(target))
+        self.visiting.remove(start_node_id)
         deduped = dedupe_terminals(found)
-        memo[current_id] = deduped
+        self.memo[start_node_id] = deduped
         return deduped
 
-    return visit(start_node_id)
-
 
 def dedupe_terminals(terminals: Iterable[dict[str, Any]]) -> list[dict[str, Any]]:
     seen: set[str] = set()
@@ -197,6 +205,10 @@ def edge_labels(node: dict[str, Any], limit: int) -> list[str]:
     return limited_unique(labels, limit)
 
 
+def has_outgoing_edges(node: dict[str, Any]) -> bool:
+    return any(isinstance(edge, dict) for edge in node.get("children") or [])
+
+
 def aggregate_examples(terminals: list[dict[str, Any]], key: str, limit: int) -> list[str]:
     values: list[str] = []
     for terminal in terminals:
@@ -268,29 +280,50 @@ def make_unit(
     }
 
 
+def node_reachable_count(node: dict[str, Any]) -> int:
+    return int_field(node, "reachable_terminals")
+
+
+def node_reachable_weight(node: dict[str, Any]) -> int:
+    return int_field(node, "reachable_weight")
+
+
 def selected_units(dag: dict[str, Any], args: Args) -> list[dict[str, Any]]:
     nodes, terminals_by_node = build_indexes(dag)
+    reachable_index = ReachableTerminalIndex(nodes, terminals_by_node)
     root = int(dag.get("root", 0) or 0)
-    candidates: list[tuple[tuple[int, int, int, int, int], dict[str, Any]]] = []
+    shared_candidates: list[tuple[tuple[int, int, int, int, int], int, dict[str, Any]]] = []
 
     for current_id, node in nodes.items():
-        terminals = reachable_terminals(current_id, nodes, terminals_by_node)
-        if not terminals:
+        if not args.include_terminal_sink_units and not has_outgoing_edges(node):
             continue
         incoming_count = int_field(node, "incoming_count")
-        reachable_count = len(terminals)
+        reachable_count = node_reachable_count(node)
         by_shared_incoming = incoming_count >= args.min_incoming_count
         by_reachable = current_id != root and reachable_count >= args.min_reachable_terminals
         if by_shared_incoming or by_reachable:
-            unit = make_unit(node, current_id, terminals, "shared_suffix", args.example_count)
             sort_key = (
                 0,
-                -unit["reachable_weight"],
-                -unit["reachable_terminals"],
-                -unit["incoming_count"],
+                -node_reachable_weight(node),
+                -reachable_count,
+                -incoming_count,
                 current_id,
             )
-            candidates.append((sort_key, unit))
+            shared_candidates.append((sort_key, current_id, node))
+
+    shared_candidates.sort(key=lambda item: item[0])
+    candidates: list[tuple[tuple[int, int, int, int, int], dict[str, Any]]] = []
+    for sort_key, current_id, node in shared_candidates:
+        if args.limit is not None and len(candidates) >= args.limit:
+            break
+        terminals = reachable_index.get(current_id)
+        if not terminals:
+            continue
+        unit = make_unit(node, current_id, terminals, "shared_suffix", args.example_count)
+        candidates.append((sort_key, unit))
+
+    if args.limit is not None and len(candidates) >= args.limit:
+        return [unit for _sort_key, unit in candidates[: max(0, args.limit)]]
 
     covered_terminal_ids = {
         terminal_id
@@ -298,10 +331,12 @@ def selected_units(dag: dict[str, Any], args: Args) -> list[dict[str, Any]]:
         for terminal_id in unit["terminal_ids"]
     }
     for current_id, terminals in terminals_by_node.items():
+        node = nodes.get(current_id, {"id": current_id})
+        if not args.include_terminal_sink_units and not has_outgoing_edges(node):
+            continue
         uncovered = [terminal for terminal in terminals if terminal["_terminal_id"] not in covered_terminal_ids]
         if not uncovered:
             continue
-        node = nodes.get(current_id, {"id": current_id})
         unit = make_unit(node, current_id, uncovered, "terminal_cluster", args.example_count)
         sort_key = (
             1,

tools/annotate_dmhy_prefix_tree_agent.py

@@ -0,0 +1,698 @@
+"""Agentic strict LLM annotator for DMHY prefix-tree terminals.
+
+This runner is intentionally separate from ``annotate_dmhy_prefix_graph.py`` so
+prefix-tree and DAG experiments can evolve independently. It reads the existing
+prefix graph plus the full DMHY source list, emits terminal annotation patches,
+and writes dmhy_weak-compatible dataset JSONL records.
+"""
+
+from __future__ import annotations
+
+import argparse
+import concurrent.futures
+import json
+import os
+import re
+import sys
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Iterable
+
+from anifilebert.tokenizer import AnimeTokenizer
+from tools.annotate_dmhy_prefix_graph import (
+    DEFAULT_GRAPH,
+    DEFAULT_MODEL,
+    DEFAULT_OUTPUT,
+    DEFAULT_PATCH_OUTPUT,
+    DEFAULT_SOURCE_LIST,
+    LLM_SOURCE,
+    dataset_records,
+    heuristic_patch,
+    load_graph,
+    selected_terminals,
+    source_list_matches,
+    string_list,
+)
+
+
+DEFAULT_BASE_URL = "http://10.137.32.209/v1"
+DEFAULT_UNITS_OUTPUT = Path("datasets/AnimeName/dmhy_prefix_graph.annotation_units.prefix_sample.jsonl")
+NON_TITLE_NUMERIC_FRAGMENT_RE = re.compile(
+    r"(?ix)^\s*"
+    r"(?:"
+    r"[\[(【《]?\s*(?:EP?|\#)?\d{1,4}(?:\s*(?:v|ver|version|rev)\s*\d{1,3})?\s*[\])】》]?|"
+    r"(?:v|ver|version|rev)\s*\d{1,3}|"
+    r"vol(?:ume)?\.?\s*\d{1,3}|"
+    r"S\d{1,2}E\d{1,4}|"
+    r"\d{1,2}x\d{1,4}"
+    r")"
+    r"\s*$"
+)
+ANNOTATION_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "additionalProperties": False,
+    "required": [
+        "terminal_id",
+        "episode_title_suffixes",
+        "media_suffixes",
+        "title_candidates",
+        "llm_label",
+        "notes",
+    ],
+    "properties": {
+        "terminal_id": {"type": "string"},
+        "episode_title_suffixes": {
+            "type": "array",
+            "items": {"type": "string"},
+        },
+        "media_suffixes": {
+            "type": "array",
+            "items": {"type": "string"},
+        },
+        "title_candidates": {
+            "type": "array",
+            "items": {"type": "string"},
+        },
+        "llm_label": {
+            "type": ["string", "null"],
+            "description": "Short classification such as accept, media_only, episode_title, mixed, or uncertain.",
+        },
+        "notes": {"type": "string"},
+    },
+}
+
+
+@dataclass(frozen=True)
+class Args:
+    graph: Path
+    source_list: Path
+    output: Path
+    patch_output: Path | None
+    units_output: Path | None
+    limit: int | None
+    min_weight: int | None
+    only_needs_review: bool
+    llm: bool
+    base_url: str
+    api_key: str | None
+    model: str
+    max_requests: int | None
+    http_timeout: int
+    preserve_i_labels: bool
+    examples_only: bool
+    workers: int
+    retries: int
+    resume: bool
+    failure_output: Path | None = None
+    reasoning_effort: str = "medium"
+
+
+def parse_args() -> Args:
+    parser = argparse.ArgumentParser(
+        description="Strict Responses API agent for annotating DMHY prefix-tree terminals"
+    )
+    parser.add_argument("--graph", type=Path, default=DEFAULT_GRAPH)
+    parser.add_argument("--source-list", type=Path, default=DEFAULT_SOURCE_LIST)
+    parser.add_argument("--output", type=Path, default=DEFAULT_OUTPUT)
+    parser.add_argument("--patch-output", default=str(DEFAULT_PATCH_OUTPUT))
+    parser.add_argument(
+        "--units-output",
+        default=str(DEFAULT_UNITS_OUTPUT),
+        help="Optional selected annotation units JSONL; use empty string to disable",
+    )
+    parser.add_argument("--limit", type=int, default=None)
+    parser.add_argument("--min-weight", type=int, default=None)
+    parser.add_argument("--only-needs-review", action="store_true")
+    parser.add_argument("--llm", action="store_true")
+    parser.add_argument(
+        "--base-url",
+        default=os.environ.get("ANIFILEBERT_LLM_BASE_URL", DEFAULT_BASE_URL),
+        help="OpenAI-compatible Responses API base URL",
+    )
+    parser.add_argument(
+        "--api-key",
+        default=os.environ.get("ANIFILEBERT_LLM_API_KEY"),
+        help="API key; prefer ANIFILEBERT_LLM_API_KEY",
+    )
+    parser.add_argument("--model", default=DEFAULT_MODEL)
+    parser.add_argument("--max-requests", type=int, default=None)
+    parser.add_argument("--http-timeout", type=int, default=120)
+    parser.add_argument("--preserve-i-labels", action="store_true")
+    parser.add_argument("--examples-only", action="store_true")
+    parser.add_argument("--workers", type=int, default=8, help="Concurrent LLM terminal patch workers")
+    parser.add_argument("--retries", type=int, default=3, help="LLM validation retry attempts per terminal")
+    parser.add_argument("--resume", action="store_true", help="Skip ok LLM terminal patches already in patch output")
+    parser.add_argument(
+        "--reasoning-effort",
+        choices=("minimal", "low", "medium", "high", "xhigh"),
+        default="medium",
+        help="Responses API reasoning effort when the target model supports reasoning",
+    )
+    parser.add_argument(
+        "--failure-output",
+        default="",
+        help="Optional JSONL path for attempted terminals that failed LLM validation/request retries",
+    )
+    ns = parser.parse_args()
+    patch_arg = str(ns.patch_output).strip()
+    units_arg = str(ns.units_output).strip()
+    failure_arg = str(ns.failure_output).strip()
+    return Args(
+        graph=ns.graph,
+        source_list=ns.source_list,
+        output=ns.output,
+        patch_output=Path(patch_arg) if patch_arg else None,
+        units_output=Path(units_arg) if units_arg else None,
+        limit=ns.limit,
+        min_weight=ns.min_weight,
+        only_needs_review=ns.only_needs_review,
+        llm=ns.llm,
+        base_url=ns.base_url,
+        api_key=ns.api_key,
+        model=ns.model,
+        max_requests=max(0, ns.max_requests) if ns.max_requests is not None else None,
+        http_timeout=ns.http_timeout,
+        preserve_i_labels=ns.preserve_i_labels,
+        examples_only=ns.examples_only,
+        workers=max(1, ns.workers),
+        retries=max(1, ns.retries),
+        resume=ns.resume,
+        failure_output=Path(failure_arg) if failure_arg else None,
+        reasoning_effort=ns.reasoning_effort,
+    )
+
+
+def responses_url(base_url: str) -> str:
+    return base_url.rstrip("/") + "/responses"
+
+
+def redact_secrets(text: str) -> str:
+    return re.sub(r"sk-[A-Za-z0-9._-]+", "sk-REDACTED", text)
+
+
+def unique_strings(value: Any, *, field: str) -> list[str]:
+    if not isinstance(value, list):
+        raise ValueError(f"{field} must be a list")
+    seen: set[str] = set()
+    result: list[str] = []
+    for item in value:
+        if not isinstance(item, str):
+            raise ValueError(f"{field} items must be strings")
+        cleaned = " ".join(item.split()).strip()
+        if cleaned and cleaned not in seen:
+            seen.add(cleaned)
+            result.append(cleaned)
+    return result
+
+
+def validate_strict_annotation(annotation: Any, *, expected_terminal_id: str) -> dict[str, Any]:
+    if not isinstance(annotation, dict):
+        raise ValueError("annotation must be a JSON object")
+    terminal_id = annotation.get("terminal_id")
+    if not isinstance(terminal_id, str):
+        raise ValueError("terminal_id must be a string")
+    if terminal_id != expected_terminal_id:
+        raise ValueError(f"terminal_id mismatch: expected {expected_terminal_id}, got {terminal_id}")
+    llm_label = annotation.get("llm_label")
+    if llm_label is not None and not isinstance(llm_label, str):
+        raise ValueError("llm_label must be a string or null")
+    notes = annotation.get("notes")
+    if not isinstance(notes, str):
+        raise ValueError("notes must be a string")
+    validated = {
+        "terminal_id": terminal_id,
+        "episode_title_suffixes": unique_strings(annotation.get("episode_title_suffixes"), field="episode_title_suffixes"),
+        "media_suffixes": unique_strings(annotation.get("media_suffixes"), field="media_suffixes"),
+        "title_candidates": unique_strings(annotation.get("title_candidates"), field="title_candidates"),
+        "llm_label": llm_label,
+        "notes": " ".join(notes.split()).strip(),
+    }
+    errors = annotation_quality_errors(validated)
+    if errors:
+        raise ValueError("; ".join(errors))
+    return validated
+
+
+def annotation_quality_errors(annotation: dict[str, Any]) -> list[str]:
+    errors: list[str] = []
+    for field in ("episode_title_suffixes", "title_candidates"):
+        values = annotation.get(field)
+        if not isinstance(values, list):
+            continue
+        bad_values = [
+            str(value)
+            for value in values
+            if isinstance(value, str) and NON_TITLE_NUMERIC_FRAGMENT_RE.fullmatch(value)
+        ]
+        if bad_values:
+            errors.append(
+                f"{field} must not contain pure episode/version/volume fragments: {bad_values[:5]}"
+            )
+    return errors
+
+
+def extract_response_annotation(data: dict[str, Any]) -> Any:
+    output_text = data.get("output_text")
+    if isinstance(output_text, str) and output_text.strip():
+        return json.loads(output_text)
+
+    for item in data.get("output") or []:
+        if not isinstance(item, dict):
+            continue
+        if item.get("type") in {"function_call", "tool_call"}:
+            arguments = item.get("arguments")
+            if isinstance(arguments, str):
+                return json.loads(arguments)
+            if isinstance(arguments, dict):
+                return arguments
+        for content in item.get("content") or []:
+            if not isinstance(content, dict):
+                continue
+            if content.get("type") in {"output_json", "json"} and "json" in content:
+                return content["json"]
+            text = content.get("text")
+            if isinstance(text, str) and text.strip():
+                return json.loads(text)
+    raise ValueError("Responses API returned no annotation payload")
+
+
+def format_error_hint(error: str | None) -> str:
+    if not error:
+        return ""
+    return (
+        "\nPrevious attempt failed validation. Correct the issue exactly and submit a new schema-valid "
+        f"annotation. Error: {error}"
+    )
+
+
+def request_body(
+    *,
+    args: Args,
+    terminal: dict[str, Any],
+    patch: dict[str, Any],
+    previous_error: str | None,
+    mode: str,
+) -> dict[str, Any]:
+    task = {
+        "terminal_id": patch["terminal_id"],
+        "prefix": terminal.get("prefix"),
+        "digit_skeleton": terminal.get("digit_skeleton"),
+        "suffix_examples": terminal.get("suffix_examples") or [],
+        "value_examples": terminal.get("value_examples") or [],
+        "heuristic_patch": {
+            "episode_title_suffixes": patch.get("episode_title_suffixes") or [],
+            "media_suffixes": patch.get("media_suffixes") or [],
+            "title_candidates": patch.get("title_candidates") or [],
+            "notes": patch.get("notes") or "",
+        },
+    }
+    instructions = (
+        "Annotate one anime filename prefix-tree terminal. Distinguish human episode-title suffix text "
+        "from media metadata such as resolution, source, codec, audio, subtitles, language, hashes, and "
+        "release tags. Do not put pure episode numbers, episode versions like 01v2, version tokens like "
+        "ver1, or volume markers like Vol.1 in episode_title_suffixes or title_candidates; those are "
+        "episode/version structure, not human title text. Keep the same terminal_id. Return only the "
+        "required strict schema data."
+        + format_error_hint(previous_error)
+    )
+    body: dict[str, Any] = {
+        "model": args.model,
+        "input": [
+            {"role": "developer", "content": instructions},
+            {"role": "user", "content": json.dumps(task, ensure_ascii=False)},
+        ],
+    }
+    if "reasoning" in mode:
+        body["reasoning"] = {"effort": args.reasoning_effort}
+    if "json_schema" in mode:
+        body["text"] = {
+            "format": {
+                "type": "json_schema",
+                "name": "dmhy_prefix_terminal_annotation",
+                "strict": True,
+                "schema": ANNOTATION_SCHEMA,
+            }
+        }
+    else:
+        body["tools"] = [
+            {
+                "type": "function",
+                "name": "submit_annotation",
+                "description": "Submit the validated DMHY terminal annotation.",
+                "strict": True,
+                "parameters": ANNOTATION_SCHEMA,
+            }
+        ]
+        body["tool_choice"] = {"type": "function", "name": "submit_annotation"}
+    return body
+
+
+def post_responses(body: dict[str, Any], args: Args) -> dict[str, Any]:
+    if not args.api_key:
+        raise RuntimeError("--llm requires --api-key or ANIFILEBERT_LLM_API_KEY")
+    request = urllib.request.Request(
+        responses_url(args.base_url),
+        data=json.dumps(body, ensure_ascii=False).encode("utf-8"),
+        headers={
+            "Authorization": f"Bearer {args.api_key}",
+            "Content-Type": "application/json",
+        },
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=args.http_timeout) as response:
+            return json.loads(response.read().decode("utf-8"))
+    except urllib.error.HTTPError as exc:
+        detail = exc.read().decode("utf-8", errors="replace")
+        raise RuntimeError(f"Responses API HTTP {exc.code}: {redact_secrets(detail[:500])}") from exc
+    except urllib.error.URLError as exc:
+        raise RuntimeError(f"Responses API request failed: {redact_secrets(str(exc.reason))}") from exc
+    except json.JSONDecodeError as exc:
+        raise RuntimeError("Responses API returned invalid response JSON") from exc
+
+
+def next_mode(mode: str, error: str) -> str:
+    lowered = error.lower()
+    if mode == "reasoning_json_schema" and "reasoning" in lowered:
+        return "json_schema"
+    if "json_schema" in mode and any(token in lowered for token in ("text.format", "json_schema", "schema")):
+        return "function_tool"
+    if mode == "reasoning_json_schema":
+        return "json_schema"
+    return mode
+
+
+def merge_llm_annotation(patch: dict[str, Any], annotation: dict[str, Any]) -> dict[str, Any]:
+    merged = dict(patch)
+    merged.update(
+        {
+            "episode_title_suffixes": annotation["episode_title_suffixes"],
+            "media_suffixes": annotation["media_suffixes"],
+            "title_candidates": annotation["title_candidates"],
+            "llm_label": annotation["llm_label"],
+            "notes": annotation["notes"],
+            "source": LLM_SOURCE,
+            "status": "ok",
+            "fallback": False,
+            "errors": [],
+        }
+    )
+    return merged
+
+
+def annotate_terminal_with_llm(
+    terminal: dict[str, Any],
+    patch: dict[str, Any],
+    args: Args,
+) -> tuple[dict[str, Any], bool]:
+    mode = "reasoning_json_schema"
+    previous_error: str | None = None
+    errors: list[str] = []
+    for _attempt in range(args.retries):
+        try:
+            body = request_body(args=args, terminal=terminal, patch=patch, previous_error=previous_error, mode=mode)
+            data = post_responses(body, args)
+            raw_annotation = extract_response_annotation(data)
+            annotation = validate_strict_annotation(raw_annotation, expected_terminal_id=str(patch["terminal_id"]))
+            return merge_llm_annotation(patch, annotation), False
+        except (RuntimeError, ValueError, json.JSONDecodeError) as exc:
+            error = redact_secrets(str(exc))
+            errors.append(error)
+            mode = next_mode(mode, error)
+            previous_error = error
+    fallback = dict(patch)
+    fallback["notes"] = f"{fallback.get('notes') or ''}; llm_error={' | '.join(errors)}"
+    fallback["status"] = "fallback"
+    fallback["fallback"] = True
+    fallback["errors"] = errors[-3:]
+    return fallback, True
+
+
+def write_jsonl(path: Path, rows: Iterable[dict[str, Any]]) -> int:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    count = 0
+    with path.open("w", encoding="utf-8", newline="\n") as handle:
+        for row in rows:
+            handle.write(json.dumps(row, ensure_ascii=False, separators=(",", ":")) + "\n")
+            count += 1
+    return count
+
+
+def is_completed_resume_row(row: dict[str, Any]) -> bool:
+    status = row.get("status")
+    source = str(row.get("source") or "")
+    if status == "ok" and source.startswith("responses"):
+        return not annotation_quality_errors(row)
+    return status is None and source == LLM_SOURCE
+
+
+def load_resume_patches(path: Path | None) -> dict[str, dict[str, Any]]:
+    if path is None or not path.exists():
+        return {}
+    completed: dict[str, dict[str, Any]] = {}
+    for line_number, line in enumerate(path.read_text(encoding="utf-8").splitlines(), 1):
+        if not line.strip():
+            continue
+        try:
+            row = json.loads(line)
+        except json.JSONDecodeError as exc:
+            raise SystemExit(f"invalid resume patch JSON in {path}:{line_number}: {exc}") from exc
+        if not isinstance(row, dict) or not is_completed_resume_row(row):
+            continue
+        keys: list[str] = []
+        for key in ("terminal_id", "unit_id"):
+            value = row.get(key)
+            if isinstance(value, (str, int)) and not isinstance(value, bool):
+                keys.append(str(value))
+        terminal_ids = row.get("terminal_ids")
+        if isinstance(terminal_ids, list):
+            keys.extend(str(item) for item in terminal_ids if isinstance(item, (str, int)) and not isinstance(item, bool))
+        for key in keys:
+            completed[key] = row
+    return completed
+
+
+def patch_from_resume_row(patch: dict[str, Any], row: dict[str, Any]) -> dict[str, Any]:
+    merged = dict(patch)
+    for key in ("episode_title_suffixes", "media_suffixes", "title_candidates"):
+        merged[key] = unique_strings(row.get(key) or [], field=key)
+    if "llm_label" in row:
+        merged["llm_label"] = row.get("llm_label")
+    if "notes" in row:
+        merged["notes"] = str(row.get("notes") or "")
+    merged["source"] = str(row.get("source") or patch.get("source") or LLM_SOURCE)
+    merged["fallback"] = False
+    merged["status"] = "ok"
+    errors = row.get("errors")
+    merged["errors"] = errors if isinstance(errors, list) else []
+    return enrich_patch(merged)
+
+
+def resume_row_for_patch(
+    resume_rows: dict[str, dict[str, Any]],
+    patch: dict[str, Any],
+) -> dict[str, Any] | None:
+    for key in (patch.get("terminal_id"), patch.get("unit_id")):
+        if key is None:
+            continue
+        row = resume_rows.get(str(key))
+        if row is not None:
+            return row
+    return None
+
+
+def annotate_selected(
+    selected: list[tuple[int, dict[str, Any], dict[str, Any]]],
+    args: Args,
+) -> tuple[list[tuple[int, int, dict[str, Any], dict[str, Any]]], int, int, int, int]:
+    resume_rows = load_resume_patches(args.patch_output) if args.resume else {}
+    results: list[dict[str, Any] | None] = [None] * len(selected)
+    pending_llm: list[tuple[int, dict[str, Any], dict[str, Any]]] = []
+    resume_skipped = 0
+
+    for ordinal, (_index, _terminal, patch) in enumerate(selected):
+        row = resume_row_for_patch(resume_rows, patch)
+        if row is not None:
+            results[ordinal] = patch_from_resume_row(patch, row)
+            resume_skipped += 1
+            continue
+        if not args.llm:
+            results[ordinal] = patch
+            continue
+        pending_llm.append((ordinal, selected[ordinal][1], patch))
+
+    candidates = pending_llm
+    if args.max_requests is not None:
+        candidates = candidates[: args.max_requests]
+
+    fallback_count = 0
+    failure_rows: list[dict[str, Any]] = []
+    if candidates:
+        with concurrent.futures.ThreadPoolExecutor(max_workers=args.workers) as executor:
+            future_to_ordinal = {
+                executor.submit(annotate_terminal_with_llm, terminal, patch, args): ordinal
+                for ordinal, terminal, patch in candidates
+            }
+            for future in concurrent.futures.as_completed(future_to_ordinal):
+                ordinal = future_to_ordinal[future]
+                try:
+                    patch, used_fallback = future.result()
+                except Exception as exc:  # defensive; worker should already convert errors to fallback
+                    patch = dict(selected[ordinal][2])
+                    patch["errors"] = [redact_secrets(str(exc))]
+                    used_fallback = True
+                if used_fallback:
+                    fallback_count += 1
+                    terminal_id = selected[ordinal][2]["terminal_id"]
+                    failure_rows.append(llm_failure_row(selected[ordinal][1], patch, args))
+                    print(f"warning: terminal {terminal_id}: LLM failed; leaving pending", file=sys.stderr)
+                    continue
+                results[ordinal] = patch
+
+    if args.failure_output is not None:
+        write_jsonl(args.failure_output, failure_rows)
+
+    completed = [
+        (ordinal, selected[ordinal][0], selected[ordinal][1], patch)
+        for ordinal, patch in enumerate(results)
+        if patch is not None
+    ]
+    pending_unprocessed = len(selected) - len(completed)
+    return completed, resume_skipped, len(candidates), fallback_count, pending_unprocessed
+
+
+def llm_failure_row(terminal: dict[str, Any], patch: dict[str, Any], args: Args) -> dict[str, Any]:
+    terminal_id = str(patch.get("terminal_id") or terminal.get("terminal_id") or "")
+    errors = patch.get("errors")
+    return {
+        "terminal_id": terminal_id,
+        "unit_id": str(patch.get("unit_id") or terminal_id),
+        "model": args.model,
+        "status": "pending",
+        "source": LLM_SOURCE,
+        "errors": errors if isinstance(errors, list) else [],
+        "prefix": terminal.get("prefix") if isinstance(terminal.get("prefix"), str) else None,
+        "digit_skeleton": terminal.get("digit_skeleton") if isinstance(terminal.get("digit_skeleton"), str) else None,
+        "suffix_examples": string_list(terminal.get("suffix_examples")),
+        "value_examples": string_list(terminal.get("value_examples")),
+    }
+
+
+def source_id(terminal: dict[str, Any], index: int, terminal_id: str) -> str | int:
+    for key in ("node_id", "id"):
+        value = terminal.get(key)
+        if isinstance(value, (str, int)) and not isinstance(value, bool):
+            return value
+    return terminal_id or index
+
+
+def int_weight(terminal: dict[str, Any]) -> int:
+    try:
+        return int(terminal.get("weight") or terminal.get("count") or 0)
+    except (TypeError, ValueError):
+        return 0
+
+
+def enrich_patch(patch: dict[str, Any]) -> dict[str, Any]:
+    terminal_id = str(patch["terminal_id"])
+    enriched = dict(patch)
+    enriched.setdefault("unit_id", terminal_id)
+    enriched.setdefault("terminal_ids", [terminal_id])
+    enriched.setdefault("status", "ok")
+    enriched.setdefault("fallback", False)
+    enriched.setdefault("errors", [])
+    return enriched
+
+
+def unit_public_row(index: int, terminal: dict[str, Any], patch: dict[str, Any]) -> dict[str, Any]:
+    terminal_id = str(patch["terminal_id"])
+    return {
+        "unit_id": str(patch.get("unit_id") or terminal_id),
+        "source_kind": "prefix_tree",
+        "source_id": source_id(terminal, index, terminal_id),
+        "terminal_ids": [terminal_id],
+        "weight": int_weight(terminal),
+        "context": {
+            "prefixes": string_list([terminal.get("prefix")] if terminal.get("prefix") is not None else []),
+            "digit_skeletons": string_list(
+                [terminal.get("digit_skeleton")] if terminal.get("digit_skeleton") is not None else []
+            ),
+            "edge_labels": [],
+            "notes": patch.get("notes") if isinstance(patch.get("notes"), str) else None,
+        },
+        "examples": {
+            "values": string_list(terminal.get("value_examples")),
+            "suffixes": string_list(terminal.get("suffix_examples")),
+        },
+        "expected_output": {"schema_version": "dmhy-annotation-v1"},
+    }
+
+
+def main() -> None:
+    args = parse_args()
+    graph = load_graph(args.graph)
+    selected = selected_terminals(graph, args)
+    if not selected:
+        raise SystemExit("no terminals selected; adjust --limit/--min-weight/--only-needs-review")
+
+    selected = [(index, terminal, enrich_patch(patch)) for index, terminal, patch in selected]
+    completed, resume_skipped, llm_requests, llm_fallbacks, pending_unprocessed = annotate_selected(selected, args)
+    tokenizer = AnimeTokenizer()
+    source_matches = None if args.examples_only else source_list_matches(args.source_list, selected)
+
+    records: list[dict[str, Any]] = []
+    patches: list[dict[str, Any]] = []
+    completed_by_ordinal = {ordinal: patch for ordinal, _index, _terminal, patch in completed}
+    for ordinal, index, terminal, patch in completed:
+        patches.append(patch)
+        records.extend(
+            dataset_records(
+                terminal,
+                index,
+                patch,
+                tokenizer,
+                filenames=None if args.examples_only else source_matches.get(ordinal, []),
+                preserve_i_labels=args.preserve_i_labels,
+            )
+        )
+
+    record_count = write_jsonl(args.output, records)
+    patch_count = 0
+    if args.patch_output is not None:
+        patch_count = write_jsonl(args.patch_output, patches)
+    unit_count = 0
+    if args.units_output is not None:
+        unit_count = write_jsonl(
+            args.units_output,
+            (
+                unit_public_row(index, terminal, completed_by_ordinal.get(ordinal, patch))
+                for ordinal, (index, terminal, patch) in enumerate(selected)
+            ),
+        )
+
+    summary = {
+        "graph": str(args.graph),
+        "source_list": None if args.examples_only else str(args.source_list),
+        "output": str(args.output),
+        "patch_output": str(args.patch_output) if args.patch_output is not None else None,
+        "units_output": str(args.units_output) if args.units_output is not None else None,
+        "selected_terminals": len(selected),
+        "examples_only": args.examples_only,
+        "dataset_records": record_count,
+        "patches": patch_count,
+        "units": unit_count,
+        "llm_enabled": args.llm,
+        "llm_requests": llm_requests,
+        "llm_fallbacks": llm_fallbacks,
+        "resume": args.resume,
+        "resume_skipped": resume_skipped,
+        "pending_unprocessed": pending_unprocessed,
+        "workers": args.workers,
+    }
+    print(json.dumps(summary, ensure_ascii=False, indent=2))
+
+
+if __name__ == "__main__":
+    main()

tools/expand_dmhy_dag_annotations.py

@@ -0,0 +1,326 @@
+"""Expand DAG annotation patches over the full DMHY source list.
+
+The DAG annotation runner samples terminal.value_examples. This tool keeps the
+LLM patch layer intact, but applies it to every dmhy_list.jsonl value by
+deterministic terminal prefix matching.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+from collections import Counter
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Iterable
+
+from anifilebert.tokenizer import AnimeTokenizer
+from tools.annotate_dmhy_prefix_graph import (
+    build_prefix_trie,
+    matching_terminal_ordinal,
+    normalize_generated_tokens,
+    prefix_boundary_ok as prefix_boundary_ok,
+)
+from tools.dmhy_dataset import weak_label_filename
+
+
+DEFAULT_DAG = Path("datasets/AnimeName/dmhy_prefix_dag.json")
+DEFAULT_SOURCE_LIST = Path("datasets/AnimeName/dmhy_list.jsonl")
+DEFAULT_PATCHES = Path("datasets/AnimeName/dmhy_prefix_dag.annotations.dag_full.jsonl")
+DEFAULT_OUTPUT = Path("datasets/AnimeName/dmhy_weak.dag_full_expanded.jsonl")
+
+
+@dataclass(frozen=True)
+class Args:
+    dag: Path
+    source_list: Path
+    patches: Path
+    output: Path
+    manifest_output: Path
+    limit: int | None
+    preserve_i_labels: bool
+    strict_boundary: bool
+
+
+def parse_args() -> Args:
+    parser = argparse.ArgumentParser(
+        description="Expand DMHY DAG terminal annotations across the full source-list"
+    )
+    parser.add_argument("--dag", type=Path, default=DEFAULT_DAG)
+    parser.add_argument("--source-list", type=Path, default=DEFAULT_SOURCE_LIST)
+    parser.add_argument("--patches", type=Path, default=DEFAULT_PATCHES)
+    parser.add_argument("--output", type=Path, default=DEFAULT_OUTPUT)
+    parser.add_argument(
+        "--manifest-output",
+        type=Path,
+        default=None,
+        help="Output manifest JSON; defaults to <output stem>.manifest.json",
+    )
+    parser.add_argument("--limit", type=int, default=None, help="Maximum source-list rows to scan")
+    parser.add_argument("--preserve-i-labels", action="store_true")
+    parser.add_argument(
+        "--strict-boundary",
+        action="store_true",
+        help="Require a separator boundary after the matched terminal prefix",
+    )
+    ns = parser.parse_args()
+    manifest_output = ns.manifest_output or ns.output.with_suffix(".manifest.json")
+    return Args(
+        dag=ns.dag,
+        source_list=ns.source_list,
+        patches=ns.patches,
+        output=ns.output,
+        manifest_output=manifest_output,
+        limit=None if ns.limit is None else max(0, ns.limit),
+        preserve_i_labels=ns.preserve_i_labels,
+        strict_boundary=ns.strict_boundary,
+    )
+
+
+def load_json(path: Path) -> dict[str, Any]:
+    if not path.exists():
+        raise SystemExit(f"file not found: {path}")
+    try:
+        value = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise SystemExit(f"invalid JSON in {path}: {exc}") from exc
+    if not isinstance(value, dict):
+        raise SystemExit(f"invalid JSON schema in {path}: root must be object")
+    return value
+
+
+def iter_jsonl(path: Path) -> Iterable[tuple[int, dict[str, Any]]]:
+    if not path.exists():
+        raise SystemExit(f"file not found: {path}")
+    with path.open("r", encoding="utf-8") as handle:
+        for line_number, line in enumerate(handle, start=1):
+            if not line.strip():
+                continue
+            try:
+                row = json.loads(line)
+            except json.JSONDecodeError as exc:
+                raise SystemExit(f"invalid JSON in {path}:{line_number}: {exc}") from exc
+            if isinstance(row, dict):
+                yield line_number, row
+
+
+def terminal_id(terminal: dict[str, Any], fallback: int) -> str:
+    for key in ("terminal_id", "id", "node_id"):
+        value = terminal.get(key)
+        if value is not None:
+            return str(value)
+    return str(fallback)
+
+
+def load_terminals(dag_path: Path) -> list[tuple[int, dict[str, Any], dict[str, Any]]]:
+    dag = load_json(dag_path)
+    terminals = dag.get("terminals")
+    if not isinstance(terminals, list):
+        raise SystemExit(f"invalid DAG schema in {dag_path}: missing terminals list")
+
+    selected: list[tuple[int, dict[str, Any], dict[str, Any]]] = []
+    for index, terminal in enumerate(terminals):
+        if not isinstance(terminal, dict):
+            continue
+        row = dict(terminal)
+        row["_terminal_id"] = terminal_id(row, index)
+        row["_terminal_index"] = index
+        if not str(row.get("prefix") or ""):
+            continue
+        selected.append((index, row, {}))
+    if not selected:
+        raise SystemExit(f"DAG has no prefix-bearing terminals: {dag_path}")
+    return selected
+
+
+def load_patches(path: Path) -> tuple[dict[str, dict[str, Any]], Counter[str]]:
+    patches_by_terminal: dict[str, dict[str, Any]] = {}
+    patch_statuses: Counter[str] = Counter()
+    for _line_number, patch in iter_jsonl(path):
+        terminal_ids = patch.get("terminal_ids")
+        if not isinstance(terminal_ids, list):
+            terminal_ids = [patch.get("terminal_id")] if patch.get("terminal_id") is not None else []
+        clean_ids = [str(item) for item in terminal_ids if str(item).strip()]
+        status = str(patch.get("status") or ("fallback" if patch.get("fallback") else "ok"))
+        patch_statuses[status] += 1
+        for tid in clean_ids:
+            patches_by_terminal[tid] = patch
+    if not patches_by_terminal:
+        raise SystemExit(f"no terminal patches found in {path}")
+    return patches_by_terminal, patch_statuses
+
+
+def matching_terminal_ordinal_relaxed(
+    value: str,
+    trie: Any,
+    selected: list[tuple[int, dict[str, Any], dict[str, Any]]],
+    *,
+    strict_boundary: bool,
+) -> int | None:
+    node = trie
+    best: int | None = None
+    for char in value:
+        node = node.children.get(char)
+        if node is None:
+            break
+        for ordinal in node.terminal_ordinals:
+            if not strict_boundary:
+                best = ordinal
+                continue
+            prefix = str(selected[ordinal][1].get("prefix") or "")
+            if prefix_boundary_ok(value, prefix):
+                best = ordinal
+    return best
+
+
+def row_from_match(
+    *,
+    filename: str,
+    source_line: int,
+    terminal: dict[str, Any],
+    patch: dict[str, Any],
+    tokenizer: AnimeTokenizer,
+    preserve_i_labels: bool,
+) -> dict[str, Any] | None:
+    sample = weak_label_filename(filename, tokenizer)
+    if sample is None:
+        return None
+    tokens, labels = normalize_generated_tokens(
+        sample["tokens"],
+        sample["labels"],
+        preserve_i_labels=preserve_i_labels,
+    )
+    terminal_id_value = str(terminal["_terminal_id"])
+    unit_id = str(patch.get("unit_id") or terminal_id_value)
+    terminal_index = terminal["_terminal_index"]
+    source = str(patch.get("source") or "unknown")
+    fallback = bool(patch.get("fallback", False))
+    status = str(patch.get("status") or ("fallback" if fallback else "ok"))
+    episode_title_suffixes = patch.get("episode_title_suffixes") or []
+    media_suffixes = patch.get("media_suffixes") or []
+    title_candidates = patch.get("title_candidates") or []
+    return {
+        "file_id": f"prefix-dag-expanded:{unit_id}:{terminal_id_value}:{source_line}",
+        "filename": filename,
+        "tokens": tokens,
+        "labels": labels,
+        "terminal_id": terminal_id_value,
+        "terminal_index": terminal_index,
+        "unit_id": unit_id,
+        "source": source,
+        "needs_llm_review": fallback,
+        "episode_title_suffixes": episode_title_suffixes,
+        "media_suffixes": media_suffixes,
+        "title_candidates": title_candidates,
+        "annotations": {
+            "unit_id": unit_id,
+            "terminal_id": terminal_id_value,
+            "terminal_ids": [str(item) for item in patch.get("terminal_ids") or [terminal_id_value]],
+            "terminal_index": terminal_index,
+            "source": source,
+            "fallback": fallback,
+            "status": status,
+            "episode_title_suffixes": episode_title_suffixes,
+            "media_suffixes": media_suffixes,
+            "title_candidates": title_candidates,
+            "llm_label": patch.get("llm_label"),
+            "notes": patch.get("notes"),
+        },
+    }
+
+
+def expand(args: Args) -> dict[str, Any]:
+    selected = load_terminals(args.dag)
+    patches_by_terminal, patch_statuses = load_patches(args.patches)
+    trie = build_prefix_trie(selected)
+    tokenizer = AnimeTokenizer()
+
+    input_rows = 0
+    matched_source_rows = 0
+    emitted_rows = 0
+    unmatched_rows = 0
+    weak_label_failed_rows = 0
+    patch_covered_rows = 0
+    unique_terminals_matched: set[str] = set()
+    status_counts: Counter[str] = Counter()
+
+    args.output.parent.mkdir(parents=True, exist_ok=True)
+    with args.output.open("w", encoding="utf-8", newline="\n") as output_handle:
+        for source_line, source_row in iter_jsonl(args.source_list):
+            if args.limit is not None and input_rows >= args.limit:
+                break
+            input_rows += 1
+            value = source_row.get("value")
+            if not isinstance(value, str) or not value.strip():
+                unmatched_rows += 1
+                status_counts["unmatched"] += 1
+                continue
+
+            ordinal = matching_terminal_ordinal_relaxed(
+                value,
+                trie,
+                selected,
+                strict_boundary=args.strict_boundary,
+            )
+            if ordinal is None:
+                unmatched_rows += 1
+                status_counts["unmatched"] += 1
+                continue
+
+            matched_source_rows += 1
+            terminal = selected[ordinal][1]
+            terminal_id_value = str(terminal["_terminal_id"])
+            unique_terminals_matched.add(terminal_id_value)
+            patch = patches_by_terminal.get(terminal_id_value)
+            if patch is None:
+                status_counts["missing_patch"] += 1
+                continue
+
+            row = row_from_match(
+                filename=value,
+                source_line=source_line,
+                terminal=terminal,
+                patch=patch,
+                tokenizer=tokenizer,
+                preserve_i_labels=args.preserve_i_labels,
+            )
+            if row is None:
+                weak_label_failed_rows += 1
+                status_counts["weak_label_failed"] += 1
+                continue
+
+            output_handle.write(json.dumps(row, ensure_ascii=False, separators=(",", ":")) + "\n")
+            emitted_rows += 1
+            patch_covered_rows += 1
+            status_counts[str(row["annotations"]["status"])] += 1
+
+    manifest = {
+        "dag": str(args.dag),
+        "source_list": str(args.source_list),
+        "patches": str(args.patches),
+        "output": str(args.output),
+        "input_rows": input_rows,
+        "matched_rows": matched_source_rows,
+        "output_rows": emitted_rows,
+        "unmatched_rows": unmatched_rows,
+        "weak_label_failed_rows": weak_label_failed_rows,
+        "patch_covered_rows": patch_covered_rows,
+        "unique_terminals_matched": len(unique_terminals_matched),
+        "status_counts": dict(sorted(status_counts.items())),
+        "patch_status_counts": dict(sorted(patch_statuses.items())),
+    }
+    args.manifest_output.parent.mkdir(parents=True, exist_ok=True)
+    args.manifest_output.write_text(
+        json.dumps(manifest, ensure_ascii=False, indent=2, sort_keys=True) + "\n",
+        encoding="utf-8",
+    )
+    return manifest
+
+
+def main() -> None:
+    manifest = expand(parse_args())
+    print(json.dumps(manifest, ensure_ascii=False, indent=2, sort_keys=True))
+
+
+if __name__ == "__main__":
+    main()

tools/test_annotate_dmhy_dag_agent.py

@@ -0,0 +1,517 @@
+"""Smoke tests for the independent DMHY DAG annotation runner."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+import tools.annotate_dmhy_dag_agent as agent
+
+
+def make_args(tmp: Path | None = None, **overrides) -> agent.Args:
+    values = {
+        "dag": Path("dag.json"),
+        "output": Path("out.jsonl"),
+        "patch_output": (tmp / "patch.jsonl") if tmp is not None else Path("patch.jsonl"),
+        "units_output": Path("units.jsonl"),
+        "limit": 10,
+        "max_requests": 10,
+        "units_per_request": 10,
+        "max_context_units": 10,
+        "workers": 8,
+        "coverage_mode": agent.COVERAGE_SHARED_ONLY,
+        "min_incoming_count": 2,
+        "min_reachable_terminals": 2,
+        "max_reachable_terminals": 500,
+        "example_count": 2,
+        "max_records": 20,
+        "records_per_terminal": 1,
+        "terminal_sink_threshold": 1000,
+        "terminal_cluster_size": 1,
+        "llm": True,
+        "base_url": "http://example.test/v1",
+        "api_key": "test-key",
+        "model": "gpt-5.4-mini",
+        "http_timeout": 1,
+        "retries": 2,
+        "preserve_i_labels": False,
+        "resume": False,
+    }
+    values.update(overrides)
+    return agent.Args(**values)
+
+
+def make_unit(unit_id: str, terminal_ids: list[str]) -> dict:
+    terminals = [
+        {
+            "_terminal_id": terminal_id,
+            "_terminal_index": index,
+            "value_examples": [f"Show {terminal_id} 01 [1080P].mkv"],
+            "suffix_examples": ["01 [1080P]"],
+            "weight": 1,
+        }
+        for index, terminal_id in enumerate(terminal_ids)
+    ]
+    return {
+        "unit_id": unit_id,
+        "node_id": 1,
+        "kind": "shared_suffix",
+        "incoming_count": 2,
+        "reachable_terminals": len(terminal_ids),
+        "reachable_weight": len(terminal_ids),
+        "terminal_ids": terminal_ids,
+        "prefix_examples": ["Show "],
+        "digit_skeleton_examples": [],
+        "value_examples": [terminal["value_examples"][0] for terminal in terminals],
+        "suffix_examples": ["01 [1080P]"],
+        "common_edge_labels": ["01"],
+        "_terminals": terminals,
+    }
+
+
+def response_for(units: list[dict], wrong_first_id: str | None = None) -> dict:
+    annotations = []
+    for index, unit in enumerate(units):
+        annotations.append(
+            {
+                "unit_id": wrong_first_id if index == 0 and wrong_first_id is not None else unit["unit_id"],
+                "terminal_ids": unit["terminal_ids"],
+                "episode_title_suffixes": [],
+                "media_suffixes": ["[1080P]"],
+                "title_candidates": [],
+                "llm_label": "media",
+                "notes": "ok",
+            }
+        )
+    return {"output_text": json.dumps({"annotations": annotations}, ensure_ascii=False)}
+
+
+class AnnotateDmhyDagAgentTests(unittest.TestCase):
+    def test_batch_request_schema_contains_annotations_array(self) -> None:
+        args = make_args()
+        units = [make_unit("u1", ["t1"]), make_unit("u2", ["t2"])]
+        body = agent.request_variants(units, args)[0]
+        schema = body["text"]["format"]["schema"]
+        self.assertEqual(body["text"]["format"]["name"], "dmhy_dag_batch_annotation")
+        self.assertIn("annotations", schema["required"])
+        self.assertEqual(schema["properties"]["annotations"]["items"]["required"][0], "unit_id")
+        payload = json.loads(body["input"])
+        self.assertEqual([unit["unit_id"] for unit in payload["units"]], ["u1", "u2"])
+
+    def test_batch_mismatch_retries_with_validation_error(self) -> None:
+        args = make_args(retries=2)
+        units = [make_unit("u1", ["t1"]), make_unit("u2", ["t2"])]
+        calls: list[dict] = []
+        original_post = agent.http_post_json
+        original_sleep = agent.time.sleep
+
+        def fake_post(body, _args):
+            calls.append(body)
+            return response_for(units, wrong_first_id="wrong") if len(calls) == 1 else response_for(units)
+
+        try:
+            agent.http_post_json = fake_post
+            agent.time.sleep = lambda _seconds: None
+            patches = agent.annotate_batch(units, args, use_llm=True)
+        finally:
+            agent.http_post_json = original_post
+            agent.time.sleep = original_sleep
+
+        self.assertEqual(len(calls), 2)
+        self.assertIn("Previous attempt failed validation", calls[1]["instructions"])
+        self.assertEqual([patch["unit_id"] for patch in patches], ["u1", "u2"])
+        self.assertTrue(all(patch["source"] == agent.LLM_SOURCE for patch in patches))
+        self.assertTrue(all(not patch["fallback"] for patch in patches))
+
+    def test_resume_skips_existing_completed_units_and_keeps_order(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            tmp = Path(tmpdir)
+            args = make_args(tmp, resume=True, units_per_request=10, max_context_units=10, workers=1)
+            units = [make_unit("u1", ["t1"]), make_unit("u2", ["t2"])]
+            args.patch_output.write_text(
+                json.dumps(
+                    {
+                        "unit_id": "u1",
+                        "terminal_ids": ["t1"],
+                        "episode_title_suffixes": ["Finale"],
+                        "media_suffixes": [],
+                        "title_candidates": [],
+                        "llm_label": "title",
+                        "notes": "existing",
+                        "source": agent.LLM_SOURCE,
+                        "fallback": False,
+                        "status": "ok",
+                        "attempts": 1,
+                        "errors": [],
+                    },
+                    ensure_ascii=False,
+                )
+                + "\n",
+                encoding="utf-8",
+            )
+            calls: list[list[str]] = []
+            original_post = agent.http_post_json
+
+            def fake_post(body, _args):
+                payload = json.loads(body["input"])
+                calls.append([unit["unit_id"] for unit in payload["units"]])
+                return response_for([units[1]])
+
+            try:
+                agent.http_post_json = fake_post
+                completed, skipped, llm_requested, pending_unprocessed = agent.annotate_units(units, args)
+            finally:
+                agent.http_post_json = original_post
+
+            self.assertEqual(skipped, 1)
+            self.assertEqual(llm_requested, 1)
+            self.assertEqual(pending_unprocessed, 0)
+            self.assertEqual(calls, [["u2"]])
+            patches = [patch for _unit, patch in completed]
+            self.assertEqual([patch["unit_id"] for patch in patches], ["u1", "u2"])
+            self.assertEqual(patches[0]["episode_title_suffixes"], ["Finale"])
+
+    def test_max_requests_partial_does_not_fallback_unprocessed_units(self) -> None:
+        args = make_args(max_requests=1, units_per_request=2, max_context_units=2, workers=1)
+        units = [make_unit("u1", ["t1"]), make_unit("u2", ["t2"]), make_unit("u3", ["t3"])]
+        calls: list[list[str]] = []
+        original_post = agent.http_post_json
+
+        def fake_post(body, _args):
+            payload = json.loads(body["input"])
+            batch_units = [unit for unit in units if unit["unit_id"] in {item["unit_id"] for item in payload["units"]}]
+            calls.append([unit["unit_id"] for unit in payload["units"]])
+            return response_for(batch_units)
+
+        try:
+            agent.http_post_json = fake_post
+            completed, skipped, llm_requested, pending_unprocessed = agent.annotate_units(units, args)
+        finally:
+            agent.http_post_json = original_post
+
+        self.assertEqual(skipped, 0)
+        self.assertEqual(llm_requested, 1)
+        self.assertEqual(pending_unprocessed, 1)
+        self.assertEqual(calls, [["u1", "u2"]])
+        patches = [patch for _unit, patch in completed]
+        self.assertEqual([patch["unit_id"] for patch in patches], ["u1", "u2"])
+        self.assertTrue(all(not patch["fallback"] for patch in patches))
+
+    def test_resume_continues_with_next_unfinished_batch(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            tmp = Path(tmpdir)
+            args = make_args(tmp, resume=True, max_requests=1, units_per_request=1, max_context_units=1, workers=1)
+            units = [make_unit("u1", ["t1"]), make_unit("u2", ["t2"]), make_unit("u3", ["t3"])]
+            args.patch_output.write_text(
+                json.dumps(
+                    {
+                        "unit_id": "u1",
+                        "terminal_ids": ["t1"],
+                        "episode_title_suffixes": [],
+                        "media_suffixes": ["[1080P]"],
+                        "title_candidates": [],
+                        "llm_label": "media",
+                        "notes": "existing",
+                        "source": agent.LLM_SOURCE,
+                        "fallback": False,
+                        "status": "ok",
+                        "attempts": 1,
+                        "errors": [],
+                    },
+                    ensure_ascii=False,
+                )
+                + "\n",
+                encoding="utf-8",
+            )
+            calls: list[list[str]] = []
+            original_post = agent.http_post_json
+
+            def fake_post(body, _args):
+                payload = json.loads(body["input"])
+                calls.append([unit["unit_id"] for unit in payload["units"]])
+                return response_for([units[1]])
+
+            try:
+                agent.http_post_json = fake_post
+                completed, skipped, llm_requested, pending_unprocessed = agent.annotate_units(units, args)
+            finally:
+                agent.http_post_json = original_post
+
+            self.assertEqual(skipped, 1)
+            self.assertEqual(llm_requested, 1)
+            self.assertEqual(pending_unprocessed, 1)
+            self.assertEqual(calls, [["u2"]])
+            self.assertEqual([unit["unit_id"] for unit, _patch in completed], ["u1", "u2"])
+
+    def test_cli_heuristic_sample_skips_terminal_sink_and_writes_dataset_rows(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            tmp = Path(tmpdir)
+            dag_path = tmp / "dag.json"
+            output_path = tmp / "dmhy_weak.dag_sample.jsonl"
+            patch_path = tmp / "patch.jsonl"
+            units_path = tmp / "units.jsonl"
+            dag_path.write_text(
+                json.dumps(
+                    {
+                        "root": 0,
+                        "nodes": [
+                            {
+                                "id": 0,
+                                "children": [{"label": "[A] Test Show - 0", "target": 1}],
+                            },
+                            {
+                                "id": 1,
+                                "terminal": False,
+                                "children": [{"label": "1 [1080P][WEB-DL]", "target": 2}],
+                                "incoming_count": 2,
+                                "reachable_terminals": 2,
+                                "reachable_weight": 2,
+                            },
+                            {
+                                "id": 2,
+                                "terminal": True,
+                                "children": [],
+                                "incoming_count": 10,
+                                "reachable_terminals": 100,
+                            },
+                        ],
+                        "terminals": [
+                            {
+                                "terminal_id": "t0",
+                                "node_id": 1,
+                                "prefix": "[A] Test Show - 0",
+                                "weight": 1,
+                                "suffix_examples": ["1 [1080P][WEB-DL]"],
+                                "value_examples": ["[A] Test Show - 01 [1080P][WEB-DL].mkv"],
+                            },
+                            {
+                                "terminal_id": "t1",
+                                "node_id": 1,
+                                "prefix": "[A] Test Show - 0",
+                                "weight": 1,
+                                "suffix_examples": ["2 [1080P][WEB-DL]"],
+                                "value_examples": ["[A] Test Show - 02 [1080P][WEB-DL].mkv"],
+                            },
+                        ],
+                    },
+                    ensure_ascii=False,
+                ),
+                encoding="utf-8",
+            )
+
+            run = subprocess.run(
+                [
+                    sys.executable,
+                    "-m",
+                    "tools.annotate_dmhy_dag_agent",
+                    "--dag",
+                    str(dag_path),
+                    "--output",
+                    str(output_path),
+                    "--patch-output",
+                    str(patch_path),
+                    "--units-output",
+                    str(units_path),
+                    "--limit",
+                    "1",
+                    "--max-requests",
+                    "0",
+                    "--workers",
+                    "2",
+                ],
+                check=False,
+                capture_output=True,
+                text=True,
+            )
+            self.assertEqual(run.returncode, 0, run.stderr)
+
+            patches = [json.loads(line) for line in patch_path.read_text(encoding="utf-8").splitlines()]
+            self.assertEqual(len(patches), 1)
+            self.assertEqual(patches[0]["unit_id"], "dag-node-1")
+            self.assertEqual(patches[0]["terminal_ids"], ["t0", "t1"])
+
+            units = [json.loads(line) for line in units_path.read_text(encoding="utf-8").splitlines()]
+            self.assertEqual(len(units), 1)
+            self.assertEqual(
+                set(units[0]),
+                {
+                    "unit_id",
+                    "source_kind",
+                    "source_id",
+                    "terminal_ids",
+                    "weight",
+                    "context",
+                    "examples",
+                    "expected_output",
+                },
+            )
+            self.assertEqual(units[0]["source_kind"], "prefix_dag")
+            self.assertEqual(units[0]["source_id"], "1")
+            self.assertEqual(units[0]["terminal_ids"], ["t0", "t1"])
+            self.assertEqual(units[0]["weight"], 2)
+            self.assertEqual(units[0]["context"]["prefixes"], ["[A] Test Show - 0"])
+            self.assertEqual(units[0]["context"]["digit_skeletons"], [])
+            self.assertEqual(units[0]["context"]["edge_labels"], ["1 [1080P][WEB-DL]"])
+            self.assertIn("incoming_count=2", units[0]["context"]["notes"])
+            self.assertEqual(
+                units[0]["examples"]["values"],
+                [
+                    "[A] Test Show - 01 [1080P][WEB-DL].mkv",
+                    "[A] Test Show - 02 [1080P][WEB-DL].mkv",
+                ],
+            )
+            self.assertEqual(units[0]["examples"]["suffixes"], ["1 [1080P][WEB-DL]", "2 [1080P][WEB-DL]"])
+            self.assertEqual(units[0]["expected_output"], {"schema_version": "dmhy-annotation-v1"})
+
+            rows = [json.loads(line) for line in output_path.read_text(encoding="utf-8").splitlines()]
+            self.assertEqual(len(rows), 2)
+            self.assertEqual(rows[0]["tokens"][0], "[")
+            self.assertTrue(all(label == "O" or label.startswith("B-") for row in rows for label in row["labels"]))
+
+    def test_cli_all_terminals_adds_terminal_cluster_for_uncovered_terminal(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            tmp = Path(tmpdir)
+            dag_path = tmp / "dag.json"
+            output_path = tmp / "dmhy_weak.dag_all.jsonl"
+            patch_path = tmp / "patch.jsonl"
+            units_path = tmp / "units.jsonl"
+            dag_path.write_text(
+                json.dumps(
+                    {
+                        "root": 0,
+                        "nodes": [
+                            {
+                                "id": 0,
+                                "children": [
+                                    {"label": "A shared", "target": 1},
+                                    {"label": "B solo", "target": 4},
+                                ],
+                            },
+                            {
+                                "id": 1,
+                                "children": [
+                                    {"label": " 01", "target": 2},
+                                    {"label": " 02", "target": 3},
+                                ],
+                                "incoming_count": 2,
+                                "reachable_terminals": 2,
+                                "reachable_weight": 20,
+                            },
+                            {
+                                "id": 2,
+                                "children": [],
+                                "incoming_count": 1,
+                                "reachable_terminals": 1,
+                                "reachable_weight": 10,
+                            },
+                            {
+                                "id": 3,
+                                "children": [],
+                                "incoming_count": 1,
+                                "reachable_terminals": 1,
+                                "reachable_weight": 10,
+                            },
+                            {
+                                "id": 4,
+                                "children": [],
+                                "incoming_count": 1,
+                                "reachable_terminals": 1,
+                                "reachable_weight": 5,
+                            },
+                        ],
+                        "terminals": [
+                            {
+                                "terminal_id": "t0",
+                                "node_id": 2,
+                                "prefix": "Shared Show 01",
+                                "weight": 10,
+                                "suffix_examples": [" [1080P]"],
+                                "value_examples": ["Shared Show 01 [1080P].mkv"],
+                            },
+                            {
+                                "terminal_id": "t1",
+                                "node_id": 3,
+                                "prefix": "Shared Show 02",
+                                "weight": 10,
+                                "suffix_examples": [" [1080P]"],
+                                "value_examples": ["Shared Show 02 [1080P].mkv"],
+                            },
+                            {
+                                "terminal_id": "t2",
+                                "node_id": 4,
+                                "prefix": "Solo Show 03",
+                                "weight": 5,
+                                "suffix_examples": [" [WEB-DL]"],
+                                "value_examples": ["Solo Show 03 [WEB-DL].mkv"],
+                            },
+                        ],
+                    },
+                    ensure_ascii=False,
+                ),
+                encoding="utf-8",
+            )
+
+            run = subprocess.run(
+                [
+                    sys.executable,
+                    "-m",
+                    "tools.annotate_dmhy_dag_agent",
+                    "--dag",
+                    str(dag_path),
+                    "--output",
+                    str(output_path),
+                    "--patch-output",
+                    str(patch_path),
+                    "--units-output",
+                    str(units_path),
+                    "--coverage-mode",
+                    "all-terminals",
+                    "--min-incoming-count",
+                    "2",
+                    "--min-reachable-terminals",
+                    "2",
+                    "--limit",
+                    "100",
+                    "--max-requests",
+                    "0",
+                ],
+                check=False,
+                capture_output=True,
+                text=True,
+            )
+            self.assertEqual(run.returncode, 0, run.stderr)
+            summary = json.loads(run.stdout)
+            self.assertEqual(summary["coverage_mode"], "all-terminals")
+            self.assertEqual(summary["dag_terminals"], 3)
+            self.assertEqual(summary["unique_terminal_coverage"], 3)
+
+            patches = [json.loads(line) for line in patch_path.read_text(encoding="utf-8").splitlines()]
+            self.assertEqual([patch["kind"] for patch in patches], ["shared_suffix", "terminal_cluster"])
+            self.assertEqual(patches[0]["terminal_ids"], ["t0", "t1"])
+            self.assertEqual(patches[1]["terminal_ids"], ["t2"])
+
+            units = [json.loads(line) for line in units_path.read_text(encoding="utf-8").splitlines()]
+            self.assertEqual(len(units), 2)
+            self.assertEqual(units[0]["unit_id"], "dag-node-1")
+            self.assertEqual(units[0]["terminal_ids"], ["t0", "t1"])
+            self.assertEqual(units[1]["unit_id"], "terminal-cluster-1")
+            self.assertEqual(units[1]["source_kind"], "prefix_dag")
+            self.assertEqual(units[1]["source_id"], "terminal-cluster-1")
+            self.assertEqual(units[1]["terminal_ids"], ["t2"])
+            self.assertIn("kind=terminal_cluster", units[1]["context"]["notes"])
+            self.assertEqual(
+                {terminal_id for unit in units for terminal_id in unit["terminal_ids"]},
+                {"t0", "t1", "t2"},
+            )
+
+            rows = [json.loads(line) for line in output_path.read_text(encoding="utf-8").splitlines()]
+            self.assertEqual({row["terminal_id"] for row in rows}, {"t0", "t1", "t2"})
+            self.assertIn("terminal-cluster-1", {row["unit_id"] for row in rows})
+
+
+if __name__ == "__main__":
+    unittest.main()

tools/test_annotated_dmhy_workflow.py

@@ -10,6 +10,14 @@ import unittest
 from pathlib import Path
 
 from tools.annotate_dmhy_prefix_graph import normalize_generated_tokens
+from tools.annotate_dmhy_prefix_tree_agent import (
+    Args as PrefixTreeAgentArgs,
+    annotate_terminal_with_llm,
+    annotate_selected,
+    enrich_patch,
+    request_body,
+    validate_strict_annotation,
+)
 from tools.convert_annotated_dmhy_dataset import (
     iter_validated_jsonl,
     validate_record,
@@ -18,6 +26,214 @@ from tools.convert_to_char_dataset import convert_record
 
 
 class AnnotatedDmhyWorkflowTests(unittest.TestCase):
+    def prefix_tree_agent_args(self) -> PrefixTreeAgentArgs:
+        return PrefixTreeAgentArgs(
+            graph=Path("graph.json"),
+            source_list=Path("source.jsonl"),
+            output=Path("out.jsonl"),
+            patch_output=Path("patch.jsonl"),
+            units_output=Path("units.jsonl"),
+            limit=None,
+            min_weight=None,
+            only_needs_review=False,
+            llm=True,
+            base_url="http://example.test/v1",
+            api_key="test-key",
+            model="gpt-5.4-mini",
+            max_requests=None,
+            http_timeout=1,
+            preserve_i_labels=False,
+            examples_only=False,
+            workers=8,
+            retries=2,
+            resume=False,
+            reasoning_effort="medium",
+        )
+
+    def prefix_selected(self, count: int = 3) -> list[tuple[int, dict, dict]]:
+        selected: list[tuple[int, dict, dict]] = []
+        for index in range(count):
+            terminal_id = f"t{index}"
+            terminal = {
+                "terminal_id": terminal_id,
+                "prefix": f"Show {index} - ",
+                "suffix_examples": [f"0{index} - Title [1080P]"],
+                "value_examples": [f"Show {index} - 0{index} - Title [1080P].mkv"],
+                "weight": index + 1,
+            }
+            patch = enrich_patch(
+                {
+                    "terminal_id": terminal_id,
+                    "needs_llm_review": True,
+                    "episode_title_suffixes": [],
+                    "media_suffixes": ["[1080P]"],
+                    "title_candidates": [],
+                    "llm_label": None,
+                    "notes": "heuristic",
+                    "source": "heuristic-v1",
+                }
+            )
+            selected.append((index, terminal, patch))
+        return selected
+
+    def test_prefix_tree_agent_max_requests_does_not_fallback_unprocessed_terminals(self) -> None:
+        args = self.prefix_tree_agent_args()
+        args = PrefixTreeAgentArgs(**{**args.__dict__, "max_requests": 1, "workers": 1})
+        selected = self.prefix_selected(3)
+
+        def fake_annotate(_terminal, patch, _args):
+            merged = dict(patch)
+            merged.update({"source": "responses-v1", "status": "ok", "fallback": False, "errors": []})
+            return merged, False
+
+        import tools.annotate_dmhy_prefix_tree_agent as agent
+
+        original_annotate = agent.annotate_terminal_with_llm
+        try:
+            agent.annotate_terminal_with_llm = fake_annotate
+            completed, resume_skipped, llm_requests, llm_fallbacks, pending_unprocessed = annotate_selected(selected, args)
+        finally:
+            agent.annotate_terminal_with_llm = original_annotate
+
+        self.assertEqual([patch["terminal_id"] for _ord, _idx, _term, patch in completed], ["t0"])
+        self.assertEqual(resume_skipped, 0)
+        self.assertEqual(llm_requests, 1)
+        self.assertEqual(llm_fallbacks, 0)
+        self.assertEqual(pending_unprocessed, 2)
+        self.assertFalse(any(patch["fallback"] for _ord, _idx, _term, patch in completed))
+
+    def test_prefix_tree_agent_resume_continues_next_batch(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            patch_path = Path(tmpdir) / "patches.jsonl"
+            patch_path.write_text(
+                json.dumps(
+                    {
+                        "terminal_id": "t0",
+                        "unit_id": "t0",
+                        "terminal_ids": ["t0"],
+                        "episode_title_suffixes": ["old"],
+                        "media_suffixes": ["[1080P]"],
+                        "title_candidates": ["old"],
+                        "llm_label": "old",
+                        "notes": "previous",
+                        "source": "responses-v1",
+                        "status": "ok",
+                        "fallback": False,
+                        "errors": [],
+                    },
+                    ensure_ascii=False,
+                    separators=(",", ":"),
+                )
+                + "\n",
+                encoding="utf-8",
+            )
+            args = self.prefix_tree_agent_args()
+            args = PrefixTreeAgentArgs(
+                **{**args.__dict__, "patch_output": patch_path, "resume": True, "max_requests": 1, "workers": 1}
+            )
+            selected = self.prefix_selected(3)
+
+            def fake_annotate(_terminal, patch, _args):
+                merged = dict(patch)
+                merged.update(
+                    {
+                        "episode_title_suffixes": [patch["terminal_id"]],
+                        "source": "responses-v1",
+                        "status": "ok",
+                        "fallback": False,
+                        "errors": [],
+                    }
+                )
+                return merged, False
+
+            import tools.annotate_dmhy_prefix_tree_agent as agent
+
+            original_annotate = agent.annotate_terminal_with_llm
+            try:
+                agent.annotate_terminal_with_llm = fake_annotate
+                completed, resume_skipped, llm_requests, _llm_fallbacks, pending_unprocessed = annotate_selected(
+                    selected, args
+                )
+            finally:
+                agent.annotate_terminal_with_llm = original_annotate
+
+            patches = [patch for _ord, _idx, _term, patch in completed]
+            self.assertEqual([patch["terminal_id"] for patch in patches], ["t0", "t1"])
+            self.assertEqual(patches[0]["notes"], "previous")
+            self.assertEqual(patches[1]["episode_title_suffixes"], ["t1"])
+            self.assertEqual(resume_skipped, 1)
+            self.assertEqual(llm_requests, 1)
+            self.assertEqual(pending_unprocessed, 1)
+
+    def test_prefix_tree_agent_completed_order_is_deterministic(self) -> None:
+        args = self.prefix_tree_agent_args()
+        args = PrefixTreeAgentArgs(**{**args.__dict__, "max_requests": 3, "workers": 3})
+        selected = self.prefix_selected(3)
+
+        def fake_annotate(_terminal, patch, _args):
+            merged = dict(patch)
+            merged.update({"source": "responses-v1", "status": "ok", "fallback": False, "errors": []})
+            return merged, False
+
+        import tools.annotate_dmhy_prefix_tree_agent as agent
+
+        original_annotate = agent.annotate_terminal_with_llm
+        try:
+            agent.annotate_terminal_with_llm = fake_annotate
+            completed, _resume_skipped, _llm_requests, _llm_fallbacks, _pending_unprocessed = annotate_selected(
+                selected, args
+            )
+        finally:
+            agent.annotate_terminal_with_llm = original_annotate
+
+        self.assertEqual([patch["terminal_id"] for _ord, _idx, _term, patch in completed], ["t0", "t1", "t2"])
+
+    def test_prefix_tree_agent_writes_llm_failures_without_completing_patches(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            failure_path = Path(tmpdir) / "failures.jsonl"
+            args = self.prefix_tree_agent_args()
+            args = PrefixTreeAgentArgs(
+                **{**args.__dict__, "max_requests": 1, "workers": 1, "failure_output": failure_path}
+            )
+            selected = self.prefix_selected(2)
+
+            def fake_annotate(_terminal, patch, _args):
+                failed = dict(patch)
+                failed.update(
+                    {
+                        "status": "fallback",
+                        "fallback": True,
+                        "errors": ["Responses API HTTP 429: busy"],
+                    }
+                )
+                return failed, True
+
+            import tools.annotate_dmhy_prefix_tree_agent as agent
+
+            original_annotate = agent.annotate_terminal_with_llm
+            try:
+                agent.annotate_terminal_with_llm = fake_annotate
+                completed, _resume_skipped, llm_requests, llm_fallbacks, pending_unprocessed = annotate_selected(
+                    selected, args
+                )
+            finally:
+                agent.annotate_terminal_with_llm = original_annotate
+
+            self.assertEqual(completed, [])
+            self.assertEqual(llm_requests, 1)
+            self.assertEqual(llm_fallbacks, 1)
+            self.assertEqual(pending_unprocessed, 2)
+            failures = [
+                json.loads(line)
+                for line in failure_path.read_text(encoding="utf-8").splitlines()
+                if line.strip()
+            ]
+            self.assertEqual(len(failures), 1)
+            self.assertEqual(failures[0]["terminal_id"], "t0")
+            self.assertEqual(failures[0]["status"], "pending")
+            self.assertEqual(failures[0]["source"], "responses-v1")
+            self.assertIn("Responses API HTTP 429", failures[0]["errors"][0])
+
     def test_generated_tokens_split_punctuation_and_use_b_only_labels(self) -> None:
         tokens, labels = normalize_generated_tokens(
             ["[ANi]", " ", "Title-Name", "07"],
@@ -39,6 +255,234 @@ class AnnotatedDmhyWorkflowTests(unittest.TestCase):
         self.assertEqual(tokens, ["Title", "-", "Name"])
         self.assertEqual(labels, ["I-TITLE", "O", "I-TITLE"])
 
+    def test_prefix_tree_agent_strict_schema_payload(self) -> None:
+        args = self.prefix_tree_agent_args()
+        terminal = {
+            "terminal_id": "t0",
+            "prefix": "Show - 01",
+            "suffix_examples": [" [1080P][WEB-DL]"],
+            "value_examples": ["Show - 01 [1080P][WEB-DL].mkv"],
+        }
+        patch = {
+            "terminal_id": "t0",
+            "episode_title_suffixes": [],
+            "media_suffixes": ["[1080P]", "[WEB-DL]"],
+            "title_candidates": [],
+            "notes": "heuristic",
+        }
+        body = request_body(args=args, terminal=terminal, patch=patch, previous_error=None, mode="reasoning_json_schema")
+        self.assertEqual(body["model"], "gpt-5.4-mini")
+        self.assertEqual(body["reasoning"], {"effort": "medium"})
+        schema_format = body["text"]["format"]
+        self.assertEqual(schema_format["type"], "json_schema")
+        self.assertTrue(schema_format["strict"])
+        self.assertIn("terminal_id", schema_format["schema"]["required"])
+        self.assertIn("episode_title_suffixes", schema_format["schema"]["required"])
+
+    def test_prefix_tree_agent_reasoning_effort_is_configurable(self) -> None:
+        args = self.prefix_tree_agent_args()
+        args = PrefixTreeAgentArgs(**{**args.__dict__, "reasoning_effort": "xhigh"})
+        body = request_body(
+            args=args,
+            terminal={"terminal_id": "t0"},
+            patch={"terminal_id": "t0", "notes": ""},
+            previous_error=None,
+            mode="reasoning_json_schema",
+        )
+        self.assertEqual(body["reasoning"], {"effort": "xhigh"})
+
+    def test_prefix_tree_agent_terminal_id_mismatch_validation(self) -> None:
+        with self.assertRaisesRegex(ValueError, "terminal_id mismatch"):
+            validate_strict_annotation(
+                {
+                    "terminal_id": "wrong",
+                    "episode_title_suffixes": [],
+                    "media_suffixes": [],
+                    "title_candidates": [],
+                    "llm_label": "uncertain",
+                    "notes": "bad id",
+                },
+                expected_terminal_id="expected",
+            )
+
+    def test_prefix_tree_agent_retries_after_terminal_id_mismatch(self) -> None:
+        args = self.prefix_tree_agent_args()
+        terminal = {
+            "terminal_id": "t0",
+            "prefix": "Show - 01",
+            "suffix_examples": [" - Finale [1080P]"],
+            "value_examples": ["Show - 01 - Finale [1080P].mkv"],
+        }
+        patch = {
+            "terminal_id": "t0",
+            "needs_llm_review": True,
+            "episode_title_suffixes": [],
+            "media_suffixes": ["[1080P]"],
+            "title_candidates": [],
+            "llm_label": None,
+            "notes": "heuristic",
+            "source": "heuristic-v1",
+        }
+        calls: list[dict] = []
+
+        def fake_post(body, _args):
+            calls.append(body)
+            terminal_id = "wrong" if len(calls) == 1 else "t0"
+            return {
+                "output_text": json.dumps(
+                    {
+                        "terminal_id": terminal_id,
+                        "episode_title_suffixes": ["Finale"],
+                        "media_suffixes": ["[1080P]"],
+                        "title_candidates": ["Finale"],
+                        "llm_label": "mixed",
+                        "notes": "validated",
+                    }
+                )
+            }
+
+        import tools.annotate_dmhy_prefix_tree_agent as agent
+
+        original_post = agent.post_responses
+        try:
+            agent.post_responses = fake_post
+            merged, used_fallback = annotate_terminal_with_llm(terminal, patch, args)
+        finally:
+            agent.post_responses = original_post
+
+        self.assertFalse(used_fallback)
+        self.assertEqual(len(calls), 2)
+        self.assertIn("Previous attempt failed validation", calls[1]["input"][0]["content"])
+        self.assertEqual(merged["terminal_id"], "t0")
+        self.assertEqual(merged["source"], "responses-v1")
+        self.assertEqual(merged["episode_title_suffixes"], ["Finale"])
+
+    def test_prefix_tree_agent_cli_writes_validator_compatible_units(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            tmp = Path(tmpdir)
+            graph_path = tmp / "graph.json"
+            dataset_path = tmp / "dmhy_weak.prefix_sample.jsonl"
+            patch_path = tmp / "patches.jsonl"
+            units_path = tmp / "units.jsonl"
+            graph_path.write_text(
+                json.dumps(
+                    {
+                        "terminals": [
+                            {
+                                "terminal_id": "t0",
+                                "node_id": 42,
+                                "prefix": "[ANi] Prefix Show - ",
+                                "digit_skeleton": "[ANi] Prefix Show - ##",
+                                "weight": 7,
+                                "value_examples": [
+                                    "[ANi] Prefix Show - 01 [1080P][WEB-DL].mkv"
+                                ],
+                                "suffix_examples": ["01 [1080P][WEB-DL]"],
+                            }
+                        ]
+                    },
+                    ensure_ascii=False,
+                ),
+                encoding="utf-8",
+            )
+
+            annotate = subprocess.run(
+                [
+                    sys.executable,
+                    "-m",
+                    "tools.annotate_dmhy_prefix_tree_agent",
+                    "--graph",
+                    str(graph_path),
+                    "--output",
+                    str(dataset_path),
+                    "--patch-output",
+                    str(patch_path),
+                    "--units-output",
+                    str(units_path),
+                    "--examples-only",
+                    "--workers",
+                    "1",
+                ],
+                check=False,
+                capture_output=True,
+                text=True,
+            )
+            self.assertEqual(annotate.returncode, 0, annotate.stderr)
+
+            units = [
+                json.loads(line)
+                for line in units_path.read_text(encoding="utf-8").splitlines()
+                if line.strip()
+            ]
+            self.assertEqual(len(units), 1)
+            self.assertEqual(
+                set(units[0]),
+                {
+                    "unit_id",
+                    "source_kind",
+                    "source_id",
+                    "terminal_ids",
+                    "weight",
+                    "context",
+                    "examples",
+                    "expected_output",
+                },
+            )
+            self.assertEqual(units[0]["unit_id"], "t0")
+            self.assertEqual(units[0]["source_kind"], "prefix_tree")
+            self.assertEqual(units[0]["source_id"], 42)
+            self.assertEqual(units[0]["terminal_ids"], ["t0"])
+            self.assertEqual(units[0]["weight"], 7)
+            self.assertEqual(units[0]["context"]["prefixes"], ["[ANi] Prefix Show - "])
+            self.assertEqual(units[0]["context"]["digit_skeletons"], ["[ANi] Prefix Show - ##"])
+            self.assertEqual(units[0]["context"]["edge_labels"], [])
+            self.assertEqual(
+                units[0]["examples"]["values"],
+                ["[ANi] Prefix Show - 01 [1080P][WEB-DL].mkv"],
+            )
+            self.assertEqual(units[0]["examples"]["suffixes"], ["01 [1080P][WEB-DL]"])
+            self.assertEqual(units[0]["expected_output"], {"schema_version": "dmhy-annotation-v1"})
+
+            patches = [
+                json.loads(line)
+                for line in patch_path.read_text(encoding="utf-8").splitlines()
+                if line.strip()
+            ]
+            self.assertEqual(patches[0]["unit_id"], "t0")
+            self.assertEqual(patches[0]["terminal_ids"], ["t0"])
+            self.assertEqual(patches[0]["status"], "ok")
+            self.assertEqual(patches[0]["errors"], [])
+            self.assertFalse(patches[0]["fallback"])
+
+            validate_units = subprocess.run(
+                [
+                    sys.executable,
+                    "-m",
+                    "tools.validate_dmhy_annotation_pipeline",
+                    "validate-units",
+                    str(units_path),
+                ],
+                check=False,
+                capture_output=True,
+                text=True,
+            )
+            self.assertEqual(validate_units.returncode, 0, validate_units.stdout + validate_units.stderr)
+            validate_patches = subprocess.run(
+                [
+                    sys.executable,
+                    "-m",
+                    "tools.validate_dmhy_annotation_pipeline",
+                    "validate-patches",
+                    str(patch_path),
+                    "--units",
+                    str(units_path),
+                ],
+                check=False,
+                capture_output=True,
+                text=True,
+            )
+            self.assertEqual(validate_patches.returncode, 0, validate_patches.stdout + validate_patches.stderr)
+
     def test_validation_rejects_embedded_punctuation(self) -> None:
         record = {
             "filename": "Title-Name 07",
@@ -440,6 +884,157 @@ class AnnotatedDmhyWorkflowTests(unittest.TestCase):
             self.assertEqual(rows[0]["common_edge_labels"], [" 01", " 02"])
             self.assertIn("annotations", rows[0])
 
+    def test_cli_dag_annotation_units_skip_terminal_sink_by_default(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            tmp = Path(tmpdir)
+            dag_path = tmp / "dmhy_prefix_dag.json"
+            output_path = tmp / "dmhy_prefix_dag.annotation_units.jsonl"
+            dag_path.write_text(
+                json.dumps(
+                    {
+                        "meta": {"version": "prefix-dag-v1"},
+                        "root": 0,
+                        "nodes": [
+                            {
+                                "id": 0,
+                                "terminal": False,
+                                "children": [{"label": "shared", "target": 2}],
+                                "incoming_count": 0,
+                                "reachable_terminals": 1,
+                                "reachable_weight": 12908,
+                            },
+                            {
+                                "id": 2,
+                                "terminal": True,
+                                "children": [],
+                                "incoming_count": 12908,
+                                "reachable_terminals": 1,
+                                "reachable_weight": 12908,
+                            },
+                        ],
+                        "terminals": [
+                            {
+                                "terminal_id": "t-sink",
+                                "node_id": 2,
+                                "prefix": "Shared Sink",
+                                "digit_skeleton": "Shared Sink",
+                                "count": 12908,
+                                "weight": 12908,
+                                "suffix_examples": [],
+                                "value_examples": ["Shared Sink.mkv"],
+                                "annotations": {},
+                            }
+                        ],
+                    },
+                    ensure_ascii=False,
+                ),
+                encoding="utf-8",
+            )
+
+            annotate = subprocess.run(
+                [
+                    sys.executable,
+                    "-m",
+                    "tools.annotate_dmhy_prefix_dag",
+                    "--dag",
+                    str(dag_path),
+                    "--output",
+                    str(output_path),
+                    "--min-reachable-terminals",
+                    "1",
+                    "--min-incoming-count",
+                    "2",
+                ],
+                check=False,
+                capture_output=True,
+                text=True,
+            )
+            self.assertEqual(annotate.returncode, 0, annotate.stderr)
+            rows = [
+                json.loads(line)
+                for line in output_path.read_text(encoding="utf-8").splitlines()
+                if line.strip()
+            ]
+            self.assertEqual(rows, [])
+
+    def test_cli_dag_annotation_units_include_terminal_sink_when_requested(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            tmp = Path(tmpdir)
+            dag_path = tmp / "dmhy_prefix_dag.json"
+            output_path = tmp / "dmhy_prefix_dag.annotation_units.jsonl"
+            dag_path.write_text(
+                json.dumps(
+                    {
+                        "meta": {"version": "prefix-dag-v1"},
+                        "root": 0,
+                        "nodes": [
+                            {
+                                "id": 0,
+                                "terminal": False,
+                                "children": [{"label": "shared", "target": 2}],
+                                "incoming_count": 0,
+                                "reachable_terminals": 1,
+                                "reachable_weight": 12908,
+                            },
+                            {
+                                "id": 2,
+                                "terminal": True,
+                                "children": [],
+                                "incoming_count": 12908,
+                                "reachable_terminals": 1,
+                                "reachable_weight": 12908,
+                            },
+                        ],
+                        "terminals": [
+                            {
+                                "terminal_id": "t-sink",
+                                "node_id": 2,
+                                "prefix": "Shared Sink",
+                                "digit_skeleton": "Shared Sink",
+                                "count": 12908,
+                                "weight": 12908,
+                                "suffix_examples": [],
+                                "value_examples": ["Shared Sink.mkv"],
+                                "annotations": {},
+                            }
+                        ],
+                    },
+                    ensure_ascii=False,
+                ),
+                encoding="utf-8",
+            )
+
+            annotate = subprocess.run(
+                [
+                    sys.executable,
+                    "-m",
+                    "tools.annotate_dmhy_prefix_dag",
+                    "--dag",
+                    str(dag_path),
+                    "--output",
+                    str(output_path),
+                    "--min-reachable-terminals",
+                    "1",
+                    "--min-incoming-count",
+                    "2",
+                    "--include-terminal-sink-units",
+                ],
+                check=False,
+                capture_output=True,
+                text=True,
+            )
+            self.assertEqual(annotate.returncode, 0, annotate.stderr)
+            rows = [
+                json.loads(line)
+                for line in output_path.read_text(encoding="utf-8").splitlines()
+                if line.strip()
+            ]
+            self.assertEqual(len(rows), 1)
+            self.assertEqual(rows[0]["unit_id"], "dag-node-2")
+            self.assertEqual(rows[0]["kind"], "shared_suffix")
+            self.assertEqual(rows[0]["terminal_ids"], ["t-sink"])
+            self.assertEqual(rows[0]["common_edge_labels"], [])
+
 
 if __name__ == "__main__":
     unittest.main()

tools/test_expand_dmhy_dag_annotations.py

@@ -0,0 +1,236 @@
+"""Tests for full source-list expansion of DAG annotation patches."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+
+def write_jsonl(path: Path, rows: list[dict]) -> None:
+    path.write_text(
+        "\n".join(json.dumps(row, ensure_ascii=False) for row in rows) + "\n",
+        encoding="utf-8",
+    )
+
+
+class ExpandDmhyDagAnnotationsTests(unittest.TestCase):
+    def run_expand(
+        self,
+        tmp: Path,
+        dag: dict,
+        source_rows: list[dict],
+        patch_rows: list[dict],
+        *,
+        limit: int | None = None,
+    ) -> tuple[list[dict], dict, subprocess.CompletedProcess[str]]:
+        dag_path = tmp / "dag.json"
+        source_path = tmp / "dmhy_list.jsonl"
+        patches_path = tmp / "patches.jsonl"
+        output_path = tmp / "expanded.jsonl"
+        manifest_path = tmp / "expanded.manifest.json"
+        dag_path.write_text(json.dumps(dag, ensure_ascii=False), encoding="utf-8")
+        write_jsonl(source_path, source_rows)
+        write_jsonl(patches_path, patch_rows)
+
+        command = [
+            sys.executable,
+            "-m",
+            "tools.expand_dmhy_dag_annotations",
+            "--dag",
+            str(dag_path),
+            "--source-list",
+            str(source_path),
+            "--patches",
+            str(patches_path),
+            "--output",
+            str(output_path),
+            "--manifest-output",
+            str(manifest_path),
+        ]
+        if limit is not None:
+            command.extend(["--limit", str(limit)])
+        run = subprocess.run(command, check=False, capture_output=True, text=True)
+        self.assertEqual(run.returncode, 0, run.stderr)
+        rows = [
+            json.loads(line)
+            for line in output_path.read_text(encoding="utf-8").splitlines()
+            if line.strip()
+        ]
+        manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+        return rows, manifest, run
+
+    def test_source_list_expands_multiple_values_for_same_terminal(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            rows, manifest, _run = self.run_expand(
+                Path(tmpdir),
+                {
+                    "nodes": [],
+                    "terminals": [
+                        {
+                            "terminal_id": "t0",
+                            "node_id": 1,
+                            "prefix": "[ANi] Full Show - ",
+                            "value_examples": ["[ANi] Full Show - 01 [1080P].mkv"],
+                        }
+                    ],
+                },
+                [
+                    {"value": "[ANi] Full Show - 01 [1080P].mkv"},
+                    {"value": "[ANi] Full Show - 02 [1080P].mkv"},
+                    {"value": "[ANi] Full Show - 03 [1080P].mkv"},
+                ],
+                [
+                    {
+                        "unit_id": "u0",
+                        "terminal_ids": ["t0"],
+                        "episode_title_suffixes": [],
+                        "media_suffixes": ["[1080P]"],
+                        "title_candidates": ["Full Show"],
+                        "source": "responses-dag-v1",
+                        "fallback": False,
+                        "status": "ok",
+                    }
+                ],
+            )
+
+            self.assertEqual([row["filename"] for row in rows], [
+                "[ANi] Full Show - 01 [1080P].mkv",
+                "[ANi] Full Show - 02 [1080P].mkv",
+                "[ANi] Full Show - 03 [1080P].mkv",
+            ])
+            self.assertTrue(all(row["terminal_id"] == "t0" for row in rows))
+            self.assertEqual(manifest["input_rows"], 3)
+            self.assertEqual(manifest["matched_rows"], 3)
+            self.assertEqual(manifest["output_rows"], 3)
+            self.assertEqual(manifest["unique_terminals_matched"], 1)
+
+    def test_unmatched_values_are_counted(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            rows, manifest, _run = self.run_expand(
+                Path(tmpdir),
+                {
+                    "nodes": [],
+                    "terminals": [
+                        {
+                            "terminal_id": "t0",
+                            "node_id": 1,
+                            "prefix": "Known Show - ",
+                            "value_examples": ["Known Show - 01 [1080P].mkv"],
+                        }
+                    ],
+                },
+                [
+                    {"value": "Known Show - 01 [1080P].mkv"},
+                    {"value": "Other Show - 01 [1080P].mkv"},
+                    {"value": ""},
+                ],
+                [
+                    {
+                        "unit_id": "u0",
+                        "terminal_ids": ["t0"],
+                        "episode_title_suffixes": [],
+                        "media_suffixes": ["[1080P]"],
+                        "title_candidates": [],
+                        "source": "responses-dag-v1",
+                        "fallback": False,
+                        "status": "ok",
+                    }
+                ],
+            )
+
+            self.assertEqual(len(rows), 1)
+            self.assertEqual(manifest["input_rows"], 3)
+            self.assertEqual(manifest["matched_rows"], 1)
+            self.assertEqual(manifest["unmatched_rows"], 2)
+            self.assertEqual(manifest["status_counts"]["unmatched"], 2)
+
+    def test_patch_with_multiple_terminal_ids_maps_to_each_terminal(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            rows, manifest, _run = self.run_expand(
+                Path(tmpdir),
+                {
+                    "nodes": [],
+                    "terminals": [
+                        {
+                            "terminal_id": "t0",
+                            "node_id": 1,
+                            "prefix": "Shared A - ",
+                            "value_examples": ["Shared A - 01 [1080P].mkv"],
+                        },
+                        {
+                            "terminal_id": "t1",
+                            "node_id": 2,
+                            "prefix": "Shared B - ",
+                            "value_examples": ["Shared B - 01 [1080P].mkv"],
+                        },
+                    ],
+                },
+                [
+                    {"value": "Shared A - 01 [1080P].mkv"},
+                    {"value": "Shared B - 02 [1080P].mkv"},
+                ],
+                [
+                    {
+                        "unit_id": "dag-node-1",
+                        "terminal_ids": ["t0", "t1"],
+                        "episode_title_suffixes": ["Finale"],
+                        "media_suffixes": ["[1080P]"],
+                        "title_candidates": ["Shared"],
+                        "source": "responses-dag-v1",
+                        "fallback": False,
+                        "status": "ok",
+                    }
+                ],
+            )
+
+            self.assertEqual([row["terminal_id"] for row in rows], ["t0", "t1"])
+            self.assertEqual({row["unit_id"] for row in rows}, {"dag-node-1"})
+            self.assertTrue(all(row["annotations"]["terminal_ids"] == ["t0", "t1"] for row in rows))
+            self.assertTrue(all(row["episode_title_suffixes"] == ["Finale"] for row in rows))
+            self.assertEqual(manifest["patch_covered_rows"], 2)
+            self.assertEqual(manifest["unique_terminals_matched"], 2)
+
+    def test_limit_scans_only_requested_source_rows(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            rows, manifest, _run = self.run_expand(
+                Path(tmpdir),
+                {
+                    "nodes": [],
+                    "terminals": [
+                        {
+                            "terminal_id": "t0",
+                            "node_id": 1,
+                            "prefix": "Limit Show - ",
+                            "value_examples": ["Limit Show - 01 [1080P].mkv"],
+                        }
+                    ],
+                },
+                [
+                    {"value": "Limit Show - 01 [1080P].mkv"},
+                    {"value": "Limit Show - 02 [1080P].mkv"},
+                ],
+                [
+                    {
+                        "unit_id": "u0",
+                        "terminal_ids": ["t0"],
+                        "episode_title_suffixes": [],
+                        "media_suffixes": ["[1080P]"],
+                        "title_candidates": [],
+                        "source": "responses-dag-v1",
+                        "fallback": False,
+                        "status": "ok",
+                    }
+                ],
+                limit=1,
+            )
+
+            self.assertEqual(len(rows), 1)
+            self.assertEqual(manifest["input_rows"], 1)
+
+
+if __name__ == "__main__":
+    unittest.main()

tools/test_schema_v2_synthetic_augment.py

@@ -0,0 +1,367 @@
+"""Integration smoke test for the schema v2 synthetic augment Rust tool."""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import subprocess
+import tempfile
+import unittest
+from pathlib import Path
+from typing import Any
+
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+MANIFEST_PATH = Path("tools/schema_v2_synthetic_augment/Cargo.toml")
+RECIPES_PATH = Path("reports/dmhy_template_recipes.full_top5000.seed.jsonl")
+LABEL_SCHEMA_PATH = Path("label_schema.json")
+NUMERIC_TITLE_SEEDS_PATH = Path("data/synthetic_numeric_titles.txt")
+PATH_PREFIX_SEEDS_PATH = Path("data/synthetic_path_prefixes.txt")
+
+CATEGORY_FIELDS = (
+    "source",
+    "source_type",
+    "augmentation",
+    "augmentation_type",
+    "augment_type",
+    "kind",
+    "category",
+    "row_type",
+    "generator",
+    "variant",
+)
+TAG_PATH_SEGMENTS = {"Gekijouban", "2004", "TV"}
+
+
+def load_jsonl(path: Path) -> list[dict[str, Any]]:
+    rows: list[dict[str, Any]] = []
+    with path.open("r", encoding="utf-8") as handle:
+        for line_no, line in enumerate(handle, 1):
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                row = json.loads(line)
+            except json.JSONDecodeError as exc:
+                raise AssertionError(f"{path}:{line_no}: invalid JSON") from exc
+            if not isinstance(row, dict):
+                raise AssertionError(f"{path}:{line_no}: row must be a JSON object")
+            rows.append(row)
+    return rows
+
+
+def load_text_lines(path: Path) -> list[str]:
+    return [
+        line.strip()
+        for line in path.read_text(encoding="utf-8").splitlines()
+        if line.strip()
+    ]
+
+
+def label_entity(label: str) -> str | None:
+    if label == "O":
+        return None
+    return label.split("-", 1)[1]
+
+
+def has_entity(row: dict[str, Any], entity: str) -> bool:
+    return any(label_entity(label) == entity for label in row["labels"])
+
+
+def has_path_entity(row: dict[str, Any]) -> bool:
+    return any(
+        (entity := label_entity(label)) is not None and entity.startswith("PATH_")
+        for label in row["labels"]
+    )
+
+
+def category_text(row: dict[str, Any]) -> str:
+    values = []
+    for field in CATEGORY_FIELDS:
+        value = row.get(field)
+        if isinstance(value, str):
+            values.append(value)
+    return " ".join(values).lower().replace("-", "_")
+
+
+def is_path_aug_row(row: dict[str, Any]) -> bool:
+    text = category_text(row)
+    return "path_aug" in text or "path_prefix" in text or has_path_entity(row)
+
+
+def is_path_series_row(row: dict[str, Any]) -> bool:
+    return "path_series" in category_text(row)
+
+
+def is_path_movie_row(row: dict[str, Any]) -> bool:
+    return "path_movie" in category_text(row)
+
+
+def is_path_special_row(row: dict[str, Any]) -> bool:
+    return "path_special" in category_text(row)
+
+
+def is_path_confuser_row(row: dict[str, Any]) -> bool:
+    return "path_confuser" in category_text(row)
+
+
+def is_numeric_title_row(row: dict[str, Any], numeric_title_seeds: list[str]) -> bool:
+    text = category_text(row)
+    if "numeric_title" in text:
+        return True
+    if is_path_aug_row(row):
+        return False
+    filename = row.get("filename")
+    return isinstance(filename, str) and any(seed in filename for seed in numeric_title_seeds)
+
+
+def span_range(filename: str, text: str, *, start_at: int = 0, end_at: int | None = None) -> range:
+    start = filename.find(text, start_at, end_at)
+    if start < 0:
+        raise AssertionError(f"span {text!r} not found in {filename!r}")
+    return range(start, start + len(text))
+
+
+def span_labels(row: dict[str, Any], text: str, *, start_at: int = 0, end_at: int | None = None) -> list[str]:
+    filename = row["filename"]
+    indexes = span_range(filename, text, start_at=start_at, end_at=end_at)
+    return [row["labels"][index] for index in indexes]
+
+
+def assert_span_not_entity(
+    testcase: unittest.TestCase,
+    row: dict[str, Any],
+    text: str,
+    entity: str,
+    *,
+    start_at: int = 0,
+    end_at: int | None = None,
+) -> None:
+    labels = span_labels(row, text, start_at=start_at, end_at=end_at)
+    testcase.assertFalse(
+        any(label_entity(label) == entity for label in labels),
+        msg=f"{text!r} in {row['filename']!r} was labeled as {entity}: {labels}",
+    )
+
+
+def iter_path_segments(filename: str) -> list[tuple[str, int, int]]:
+    segments: list[tuple[str, int, int]] = []
+    start = 0
+    for match in re.finditer(r"[\\/]", filename):
+        end = match.start()
+        if end > start:
+            segments.append((filename[start:end], start, end))
+        start = match.end()
+    if start < len(filename):
+        segments.append((filename[start:], start, len(filename)))
+    return segments
+
+
+class SchemaV2SyntheticAugmentSmokeTests(unittest.TestCase):
+    tmpdir: tempfile.TemporaryDirectory[str]
+    output_path: Path
+    manifest_output_path: Path
+    rows: list[dict[str, Any]]
+    manifest: dict[str, Any]
+    allowed_labels: set[str]
+    numeric_title_seeds: list[str]
+
+    @classmethod
+    def setUpClass(cls) -> None:
+        cls.tmpdir = tempfile.TemporaryDirectory(prefix="anifilebert_schema_v2_aug_")
+        tmp_path = Path(cls.tmpdir.name)
+        cls.output_path = tmp_path / "aug.jsonl"
+        cls.manifest_output_path = tmp_path / "aug.manifest.json"
+        cls.numeric_title_seeds = load_text_lines(REPO_ROOT / NUMERIC_TITLE_SEEDS_PATH)
+        cls.allowed_labels = set(
+            json.loads((REPO_ROOT / LABEL_SCHEMA_PATH).read_text(encoding="utf-8"))[
+                "labels"
+            ]
+        )
+
+        command = [
+            "cargo",
+            "run",
+            "--manifest-path",
+            str(MANIFEST_PATH),
+            "--bin",
+            "schema_v2_synthetic_augment",
+            "--",
+            "--recipes",
+            str(RECIPES_PATH),
+            "--label-schema-file",
+            str(LABEL_SCHEMA_PATH),
+            "--numeric-title-seeds",
+            str(NUMERIC_TITLE_SEEDS_PATH),
+            "--path-prefix-seeds",
+            str(PATH_PREFIX_SEEDS_PATH),
+            "--limit-templates",
+            "80",
+            "--max-rows",
+            "2000",
+            "--output",
+            str(cls.output_path),
+            "--manifest-output",
+            str(cls.manifest_output_path),
+        ]
+        env = os.environ.copy()
+        env["CARGO_TARGET_DIR"] = str(tmp_path / "cargo-target")
+        result = subprocess.run(
+            command,
+            cwd=REPO_ROOT,
+            env=env,
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+        )
+        if result.returncode != 0:
+            raise RuntimeError(
+                "\n".join(
+                    [
+                        f"cargo run failed with exit code {result.returncode}",
+                        "command: " + " ".join(command),
+                        "stdout:",
+                        result.stdout.strip(),
+                        "stderr:",
+                        result.stderr.strip(),
+                    ]
+                )
+            )
+
+        cls.rows = load_jsonl(cls.output_path)
+        cls.manifest = json.loads(
+            cls.manifest_output_path.read_text(encoding="utf-8")
+        )
+
+    @classmethod
+    def tearDownClass(cls) -> None:
+        cls.tmpdir.cleanup()
+
+    def test_jsonl_rows_are_char_tokenized_and_strict_bio(self) -> None:
+        self.assertGreater(len(self.rows), 0, "generator produced no rows")
+        for row_number, row in enumerate(self.rows, 1):
+            with self.subTest(row=row_number):
+                self.assertIsInstance(row.get("filename"), str)
+                self.assertEqual(row["tokens"], list(row["filename"]))
+                self.assertEqual(len(row["tokens"]), len(row["labels"]))
+
+                previous_entity: str | None = None
+                for index, label in enumerate(row["labels"]):
+                    self.assertIn(label, self.allowed_labels)
+                    if label == "O":
+                        previous_entity = None
+                        continue
+                    prefix, entity = label.split("-", 1)
+                    self.assertIn(prefix, {"B", "I"})
+                    if prefix == "I":
+                        self.assertEqual(
+                            previous_entity,
+                            entity,
+                            msg=(
+                                f"orphan I-tag at row {row_number}, index {index}: "
+                                f"{label} in {row['filename']!r}"
+                            ),
+                        )
+                    previous_entity = entity
+
+    def test_manifest_counts_match_data_categories(self) -> None:
+        required_keys = {"generated_rows", "numeric_title_rows", "path_rows"}
+        self.assertFalse(required_keys - self.manifest.keys())
+
+        numeric_title_rows = [
+            row for row in self.rows if is_numeric_title_row(row, self.numeric_title_seeds)
+        ]
+        path_aug_rows = [row for row in self.rows if is_path_aug_row(row)]
+        path_series_rows = [row for row in self.rows if is_path_series_row(row)]
+        path_movie_rows = [row for row in self.rows if is_path_movie_row(row)]
+        path_special_rows = [row for row in self.rows if is_path_special_row(row)]
+        path_confuser_rows = [row for row in self.rows if is_path_confuser_row(row)]
+
+        self.assertGreater(len(numeric_title_rows), 0)
+        self.assertGreater(len(path_aug_rows), 0)
+        self.assertGreater(len(path_series_rows), 0)
+        self.assertGreater(len(path_movie_rows), 0)
+        self.assertGreater(len(path_special_rows), 0)
+        self.assertGreater(len(path_confuser_rows), 0)
+        self.assertEqual(self.manifest["generated_rows"], len(self.rows))
+        self.assertEqual(self.manifest["numeric_title_rows"], len(numeric_title_rows))
+        self.assertEqual(self.manifest["path_rows"], len(path_aug_rows))
+        self.assertEqual(self.manifest["path_series_rows"], len(path_series_rows))
+        self.assertEqual(self.manifest["path_movie_rows"], len(path_movie_rows))
+        self.assertEqual(self.manifest["path_special_rows"], len(path_special_rows))
+        self.assertEqual(self.manifest["path_confuser_rows"], len(path_confuser_rows))
+        self.assertEqual(
+            self.manifest["path_rows"],
+            self.manifest["path_series_rows"]
+            + self.manifest["path_movie_rows"]
+            + self.manifest["path_special_rows"]
+            + self.manifest["path_confuser_rows"],
+        )
+
+    def test_numeric_title_digits_are_not_episode(self) -> None:
+        for title, numeric_part in (("91 Days", "91"), ("7-nin", "7")):
+            matches = [row for row in self.rows if title in row["filename"]]
+            self.assertGreater(len(matches), 0, f"missing numeric title sample {title!r}")
+            for row in matches:
+                title_start = row["filename"].find(title)
+                title_end = title_start + len(title)
+                assert_span_not_entity(
+                    self,
+                    row,
+                    numeric_part,
+                    "EPISODE",
+                    start_at=title_start,
+                    end_at=title_end,
+                )
+
+    def test_special_codes_do_not_create_episode_labels(self) -> None:
+        special_cases = ("[NCOP2]", "[NCED]", "[PV][01]")
+        seen: set[str] = set()
+        for row in self.rows:
+            filename = row["filename"]
+            for special in special_cases:
+                if special not in filename:
+                    continue
+                seen.add(special)
+                assert_span_not_entity(self, row, special, "EPISODE")
+                self.assertIn("B-SPECIAL", span_labels(row, special))
+        self.assertEqual(
+            seen,
+            set(special_cases),
+            msg=f"missing special-code samples: {sorted(set(special_cases) - seen)}",
+        )
+
+    def test_path_aug_labels_path_title_path_season_and_tag_directories(self) -> None:
+        path_rows = [row for row in self.rows if is_path_aug_row(row)]
+        self.assertTrue(any(has_entity(row, "PATH_TITLE_LATIN") for row in path_rows))
+        self.assertTrue(any(has_entity(row, "PATH_SEASON") for row in path_rows))
+        self.assertTrue(any(is_path_confuser_row(row) for row in path_rows))
+
+        seen_tag_segments: set[str] = set()
+        for row in path_rows:
+            for segment, start, end in iter_path_segments(row["filename"]):
+                if segment not in TAG_PATH_SEGMENTS:
+                    continue
+                seen_tag_segments.add(segment)
+                labels = row["labels"][start:end]
+                self.assertEqual(
+                    labels,
+                    ["B-TAG", *(["I-TAG"] * (len(segment) - 1))],
+                    msg=f"path segment {segment!r} should be TAG in {row['filename']!r}",
+                )
+                self.assertFalse(
+                    any(label_entity(label) == "PATH_SEASON" for label in labels),
+                    msg=f"path segment {segment!r} should not be PATH_SEASON",
+                )
+
+        self.assertEqual(
+            seen_tag_segments,
+            TAG_PATH_SEGMENTS,
+            msg=f"missing path tag samples: {sorted(TAG_PATH_SEGMENTS - seen_tag_segments)}",
+        )
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)

tools/test_validate_dmhy_annotation_pipeline.py

@@ -0,0 +1,141 @@
+"""Tests for the DMHY annotation pipeline interchange validator."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+
+class DmhyAnnotationPipelineValidatorTests(unittest.TestCase):
+    def write_jsonl(self, path: Path, rows: list[dict]) -> None:
+        path.write_text(
+            "".join(json.dumps(row, ensure_ascii=False) + "\n" for row in rows),
+            encoding="utf-8",
+        )
+
+    def unit(self, terminal_ids: list[str] | None = None) -> dict:
+        return {
+            "unit_id": "u-1",
+            "source_kind": "prefix_tree",
+            "source_id": "t-1",
+            "terminal_ids": terminal_ids or ["t-1", "t-2"],
+            "weight": 2,
+            "context": {
+                "prefixes": ["Show - 01"],
+                "digit_skeletons": ["Show - ##"],
+                "edge_labels": [" [1080p]"],
+                "notes": None,
+            },
+            "examples": {
+                "values": ["Show - 01 [1080p].mkv"],
+                "suffixes": [" [1080p]"],
+            },
+            "expected_output": {"schema_version": "dmhy-annotation-v1"},
+        }
+
+    def patch(self, terminal_ids: list[str] | None = None, status: str = "ok") -> dict:
+        return {
+            "unit_id": "u-1",
+            "terminal_ids": terminal_ids or ["t-1", "t-2"],
+            "annotation": {
+                "episode_title_suffixes": [],
+                "media_suffixes": ["[1080p]"],
+                "title_candidates": [],
+                "llm_label": None,
+                "notes": "clean",
+            },
+            "status": status,
+            "errors": [],
+        }
+
+    def run_cli(self, *args: str) -> subprocess.CompletedProcess[str]:
+        return subprocess.run(
+            [sys.executable, "-m", "tools.validate_dmhy_annotation_pipeline", *args],
+            check=False,
+            capture_output=True,
+            text=True,
+        )
+
+    def test_validate_units_and_manifest(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            tmp = Path(tmpdir)
+            units = tmp / "units.jsonl"
+            manifest = tmp / "manifest.json"
+            self.write_jsonl(units, [self.unit()])
+
+            result = self.run_cli("validate-units", str(units), "--manifest-output", str(manifest))
+
+            self.assertEqual(result.returncode, 0, result.stderr)
+            report = json.loads(manifest.read_text(encoding="utf-8"))
+            self.assertEqual(report["total_rows"], 1)
+            self.assertEqual(report["error_count"], 0)
+            self.assertEqual(report["terminal_coverage_count"], 2)
+
+    def test_validate_patches_reports_terminal_mismatch(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            tmp = Path(tmpdir)
+            units = tmp / "units.jsonl"
+            patches = tmp / "patches.jsonl"
+            self.write_jsonl(units, [self.unit(["t-1", "t-2"])])
+            self.write_jsonl(patches, [self.patch(["t-1"])])
+
+            result = self.run_cli("validate-patches", str(patches), "--units", str(units))
+
+            self.assertEqual(result.returncode, 1)
+            report = json.loads(result.stdout)
+            self.assertEqual(report["terminal_id_mismatch_count"], 1)
+            self.assertEqual(report["common_field_errors"]["terminal_ids.mismatch"], 1)
+
+    def test_compare_patches_counts_statuses_intersection_and_empty_rates(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            tmp = Path(tmpdir)
+            left = tmp / "tree.jsonl"
+            right = tmp / "dag.jsonl"
+            left_rows = [
+                self.patch(["t-1", "t-2"], "ok"),
+                {
+                    **self.patch(["t-3"], "fallback"),
+                    "unit_id": "u-2",
+                    "annotation": {
+                        "episode_title_suffixes": [],
+                        "media_suffixes": [],
+                        "title_candidates": [],
+                        "llm_label": None,
+                        "notes": "empty fallback",
+                    },
+                },
+            ]
+            right_rows = [
+                self.patch(["t-2", "t-4"], "failed"),
+            ]
+            right_rows[0]["errors"] = ["timeout"]
+            self.write_jsonl(left, left_rows)
+            self.write_jsonl(right, right_rows)
+
+            result = self.run_cli(
+                "compare-patches",
+                str(left),
+                str(right),
+                "--left-label",
+                "prefix_tree",
+                "--right-label",
+                "prefix_dag",
+            )
+
+            self.assertEqual(result.returncode, 0, result.stderr)
+            report = json.loads(result.stdout)
+            self.assertEqual(report["left"]["status_counts"]["ok"], 1)
+            self.assertEqual(report["left"]["status_counts"]["fallback"], 1)
+            self.assertEqual(report["right"]["status_counts"]["failed"], 1)
+            self.assertEqual(report["terminal_intersection_count"], 1)
+            self.assertEqual(report["terminal_union_count"], 4)
+            self.assertEqual(report["left"]["annotation_empty_rates"]["all_annotation_arrays"], 0.5)
+            self.assertEqual(report["right"]["text_summary"]["errors"][0]["text"], "timeout")
+
+
+if __name__ == "__main__":
+    unittest.main()

tools/validate_dmhy_annotation_pipeline.py

@@ -0,0 +1,446 @@
+"""Validate and compare DMHY annotation pipeline interchange JSONL.
+
+This tool is intentionally independent from the prefix-tree and DAG runners.
+It defines the shared annotation-unit and annotation-patch contract that both
+pipelines can emit while they evolve separately.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from collections import Counter
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Iterable
+
+
+SCHEMA_VERSION = "dmhy-annotation-v1"
+SOURCE_KINDS = {"prefix_tree", "prefix_dag"}
+PATCH_STATUSES = {"ok", "fallback", "failed"}
+ANNOTATION_ARRAY_FIELDS = (
+    "episode_title_suffixes",
+    "media_suffixes",
+    "title_candidates",
+)
+
+
+@dataclass(frozen=True)
+class JsonlRow:
+    path: Path
+    line_number: int
+    value: Any
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Validate and compare DMHY annotation-unit and patch JSONL files"
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    units = subparsers.add_parser("validate-units", help="Validate annotation-unit JSONL")
+    units.add_argument("units_jsonl", type=Path)
+    units.add_argument("--manifest-output", type=Path)
+
+    patches = subparsers.add_parser("validate-patches", help="Validate annotation-patch JSONL")
+    patches.add_argument("patches_jsonl", type=Path)
+    patches.add_argument("--units", type=Path, help="Optional units JSONL for terminal_id mismatch checks")
+    patches.add_argument("--manifest-output", type=Path)
+
+    compare = subparsers.add_parser("compare-patches", help="Compare two annotation-patch JSONL files")
+    compare.add_argument("left_patches_jsonl", type=Path)
+    compare.add_argument("right_patches_jsonl", type=Path)
+    compare.add_argument("--left-label", default="left")
+    compare.add_argument("--right-label", default="right")
+    compare.add_argument("--manifest-output", type=Path)
+    compare.add_argument("--summary-limit", type=int, default=8)
+
+    return parser.parse_args()
+
+
+def iter_jsonl(path: Path) -> Iterable[JsonlRow]:
+    if not path.exists():
+        raise SystemExit(f"JSONL not found: {path}")
+    with path.open("r", encoding="utf-8") as handle:
+        for line_number, line in enumerate(handle, start=1):
+            if not line.strip():
+                continue
+            try:
+                value = json.loads(line)
+            except json.JSONDecodeError as exc:
+                yield JsonlRow(path, line_number, {"__json_error__": str(exc)})
+                continue
+            yield JsonlRow(path, line_number, value)
+
+
+def error_key(message: str) -> str:
+    return message.split(":", 1)[0]
+
+
+def add_error(errors: list[str], field_errors: Counter[str], message: str) -> None:
+    errors.append(message)
+    field_errors[error_key(message)] += 1
+
+
+def is_string_list(value: Any) -> bool:
+    return isinstance(value, list) and all(isinstance(item, str) for item in value)
+
+
+def is_int_not_bool(value: Any) -> bool:
+    return isinstance(value, int) and not isinstance(value, bool)
+
+
+def validate_unit_row(row: Any) -> tuple[list[str], str | None, list[str]]:
+    field_errors: Counter[str] = Counter()
+    errors: list[str] = []
+    if not isinstance(row, dict):
+        add_error(errors, field_errors, "row_type: expected object")
+        return errors, None, []
+
+    unit_id = row.get("unit_id")
+    terminal_ids = row.get("terminal_ids")
+    if not isinstance(unit_id, str) or not unit_id:
+        add_error(errors, field_errors, "unit_id: expected non-empty string")
+    if row.get("source_kind") not in SOURCE_KINDS:
+        add_error(errors, field_errors, "source_kind: expected prefix_tree or prefix_dag")
+    source_id = row.get("source_id")
+    if not isinstance(source_id, (str, int)) or isinstance(source_id, bool):
+        add_error(errors, field_errors, "source_id: expected string or integer")
+    if not is_string_list(terminal_ids):
+        add_error(errors, field_errors, "terminal_ids: expected string array")
+        clean_terminal_ids: list[str] = []
+    else:
+        clean_terminal_ids = terminal_ids
+    if not is_int_not_bool(row.get("weight")):
+        add_error(errors, field_errors, "weight: expected integer")
+
+    context = row.get("context")
+    if not isinstance(context, dict):
+        add_error(errors, field_errors, "context: expected object")
+    else:
+        for key in ("prefixes", "digit_skeletons", "edge_labels"):
+            if not is_string_list(context.get(key)):
+                add_error(errors, field_errors, f"context.{key}: expected string array")
+        if context.get("notes") is not None and not isinstance(context.get("notes"), str):
+            add_error(errors, field_errors, "context.notes: expected string or null")
+
+    examples = row.get("examples")
+    if not isinstance(examples, dict):
+        add_error(errors, field_errors, "examples: expected object")
+    else:
+        for key in ("values", "suffixes"):
+            if not is_string_list(examples.get(key)):
+                add_error(errors, field_errors, f"examples.{key}: expected string array")
+
+    expected_output = row.get("expected_output")
+    if not isinstance(expected_output, dict):
+        add_error(errors, field_errors, "expected_output: expected object")
+    elif expected_output.get("schema_version") != SCHEMA_VERSION:
+        add_error(errors, field_errors, f"expected_output.schema_version: expected {SCHEMA_VERSION}")
+
+    return errors, unit_id if isinstance(unit_id, str) else None, clean_terminal_ids
+
+
+def normalize_patch_row(row: Any) -> dict[str, Any]:
+    """Return the canonical patch view, accepting legacy flat patch rows too."""
+    if not isinstance(row, dict):
+        return {}
+    annotation = row.get("annotation")
+    if isinstance(annotation, dict):
+        annotation_obj = annotation
+    else:
+        annotation_obj = {
+            key: row.get(key)
+            for key in (*ANNOTATION_ARRAY_FIELDS, "llm_label", "notes")
+            if key in row
+        }
+    status = row.get("status")
+    if status is None:
+        source = str(row.get("source") or "")
+        if row.get("fallback") is True:
+            status = "fallback"
+        elif source.startswith("responses"):
+            status = "ok"
+        else:
+            status = "ok"
+    errors = row.get("errors")
+    if errors is None:
+        errors = []
+    return {
+        "unit_id": row.get("unit_id", row.get("terminal_id")),
+        "terminal_ids": row.get("terminal_ids", [row["terminal_id"]] if "terminal_id" in row else None),
+        "annotation": annotation_obj,
+        "status": status,
+        "errors": errors,
+    }
+
+
+def validate_patch_row(row: Any) -> tuple[list[str], str | None, list[str], dict[str, Any]]:
+    field_errors: Counter[str] = Counter()
+    errors: list[str] = []
+    canonical = normalize_patch_row(row)
+    if not isinstance(row, dict):
+        add_error(errors, field_errors, "row_type: expected object")
+        return errors, None, [], canonical
+
+    unit_id = canonical.get("unit_id")
+    terminal_ids = canonical.get("terminal_ids")
+    annotation = canonical.get("annotation")
+    if not isinstance(unit_id, str) or not unit_id:
+        add_error(errors, field_errors, "unit_id: expected non-empty string")
+    if not is_string_list(terminal_ids):
+        add_error(errors, field_errors, "terminal_ids: expected string array")
+        clean_terminal_ids: list[str] = []
+    else:
+        clean_terminal_ids = terminal_ids
+    if not isinstance(annotation, dict):
+        add_error(errors, field_errors, "annotation: expected object")
+    else:
+        for key in ANNOTATION_ARRAY_FIELDS:
+            if not is_string_list(annotation.get(key)):
+                add_error(errors, field_errors, f"annotation.{key}: expected string array")
+        if annotation.get("llm_label") is not None and not isinstance(annotation.get("llm_label"), str):
+            add_error(errors, field_errors, "annotation.llm_label: expected string or null")
+        if annotation.get("notes") is not None and not isinstance(annotation.get("notes"), str):
+            add_error(errors, field_errors, "annotation.notes: expected string or null")
+    if canonical.get("status") not in PATCH_STATUSES:
+        add_error(errors, field_errors, "status: expected ok, fallback, or failed")
+    if not is_string_list(canonical.get("errors")):
+        add_error(errors, field_errors, "errors: expected string array")
+    return errors, unit_id if isinstance(unit_id, str) else None, clean_terminal_ids, canonical
+
+
+def terminal_set(ids: Iterable[str]) -> set[str]:
+    return {str(item) for item in ids if str(item)}
+
+
+def unit_index(path: Path) -> tuple[dict[str, set[str]], dict[str, Any]]:
+    units: dict[str, set[str]] = {}
+    report = validate_units(path)
+    for item in report["valid_units"]:
+        units[item["unit_id"]] = set(item["terminal_ids"])
+    return units, report
+
+
+def summarize_report(report: dict[str, Any], manifest_output: Path | None) -> None:
+    printable = {key: value for key, value in report.items() if not key.startswith("valid_")}
+    text = json.dumps(printable, ensure_ascii=False, indent=2, sort_keys=True)
+    print(text)
+    if manifest_output is not None:
+        manifest_output.parent.mkdir(parents=True, exist_ok=True)
+        manifest_output.write_text(text + "\n", encoding="utf-8")
+
+
+def validate_units(path: Path) -> dict[str, Any]:
+    field_errors: Counter[str] = Counter()
+    duplicate_unit_ids = 0
+    seen_unit_ids: set[str] = set()
+    valid_units: list[dict[str, Any]] = []
+    total = 0
+    error_rows = 0
+    for jsonl_row in iter_jsonl(path):
+        total += 1
+        row = jsonl_row.value
+        if isinstance(row, dict) and "__json_error__" in row:
+            field_errors["json"] += 1
+            error_rows += 1
+            continue
+        errors, unit_id, terminal_ids = validate_unit_row(row)
+        for message in errors:
+            field_errors[error_key(message)] += 1
+        if unit_id:
+            if unit_id in seen_unit_ids:
+                duplicate_unit_ids += 1
+                field_errors["unit_id.duplicate"] += 1
+                errors.append("unit_id.duplicate")
+            seen_unit_ids.add(unit_id)
+        if errors:
+            error_rows += 1
+        else:
+            valid_units.append({"unit_id": unit_id, "terminal_ids": terminal_ids})
+    return {
+        "schema": "dmhy_annotation_units",
+        "schema_version": SCHEMA_VERSION,
+        "path": str(path),
+        "total_rows": total,
+        "error_rows": error_rows,
+        "error_count": sum(field_errors.values()),
+        "common_field_errors": dict(field_errors.most_common()),
+        "duplicate_unit_ids": duplicate_unit_ids,
+        "terminal_coverage_count": len({tid for unit in valid_units for tid in unit["terminal_ids"]}),
+        "valid_units": valid_units,
+    }
+
+
+def validate_patches(path: Path, units_path: Path | None = None) -> dict[str, Any]:
+    field_errors: Counter[str] = Counter()
+    status_counts: Counter[str] = Counter()
+    duplicate_unit_ids = 0
+    seen_unit_ids: set[str] = set()
+    valid_patches: list[dict[str, Any]] = []
+    total = 0
+    error_rows = 0
+    terminal_mismatch_count = 0
+    unknown_unit_count = 0
+    units_by_id: dict[str, set[str]] = {}
+    units_report: dict[str, Any] | None = None
+    if units_path is not None:
+        units_by_id, units_report = unit_index(units_path)
+
+    for jsonl_row in iter_jsonl(path):
+        total += 1
+        row = jsonl_row.value
+        if isinstance(row, dict) and "__json_error__" in row:
+            field_errors["json"] += 1
+            error_rows += 1
+            continue
+        errors, unit_id, terminal_ids, canonical = validate_patch_row(row)
+        for message in errors:
+            field_errors[error_key(message)] += 1
+        if unit_id:
+            if unit_id in seen_unit_ids:
+                duplicate_unit_ids += 1
+                field_errors["unit_id.duplicate"] += 1
+                errors.append("unit_id.duplicate")
+            seen_unit_ids.add(unit_id)
+            if units_by_id:
+                expected = units_by_id.get(unit_id)
+                if expected is None:
+                    unknown_unit_count += 1
+                    field_errors["unit_id.unknown"] += 1
+                    errors.append("unit_id.unknown")
+                elif set(terminal_ids) != expected:
+                    terminal_mismatch_count += 1
+                    field_errors["terminal_ids.mismatch"] += 1
+                    errors.append("terminal_ids.mismatch")
+        if isinstance(canonical.get("status"), str):
+            status_counts[str(canonical["status"])] += 1
+        if errors:
+            error_rows += 1
+        else:
+            valid_patches.append(canonical)
+
+    return {
+        "schema": "dmhy_annotation_patches",
+        "schema_version": SCHEMA_VERSION,
+        "path": str(path),
+        "units_path": str(units_path) if units_path else None,
+        "total_rows": total,
+        "error_rows": error_rows,
+        "error_count": sum(field_errors.values()),
+        "common_field_errors": dict(field_errors.most_common()),
+        "duplicate_unit_ids": duplicate_unit_ids,
+        "terminal_id_mismatch_count": terminal_mismatch_count,
+        "unknown_unit_count": unknown_unit_count,
+        "status_counts": {status: status_counts.get(status, 0) for status in sorted(PATCH_STATUSES)},
+        "terminal_coverage_count": len({tid for patch in valid_patches for tid in patch["terminal_ids"]}),
+        "units_validation": None
+        if units_report is None
+        else {key: value for key, value in units_report.items() if not key.startswith("valid_")},
+        "valid_patches": valid_patches,
+    }
+
+
+def annotation_empty_rates(patches: list[dict[str, Any]]) -> dict[str, float]:
+    if not patches:
+        return {key: 0.0 for key in (*ANNOTATION_ARRAY_FIELDS, "all_annotation_arrays")}
+    counts: Counter[str] = Counter()
+    for patch in patches:
+        annotation = patch.get("annotation") or {}
+        all_empty = True
+        for key in ANNOTATION_ARRAY_FIELDS:
+            empty = not annotation.get(key)
+            counts[key] += int(empty)
+            all_empty = all_empty and empty
+        counts["all_annotation_arrays"] += int(all_empty)
+    return {key: round(counts[key] / len(patches), 6) for key in (*ANNOTATION_ARRAY_FIELDS, "all_annotation_arrays")}
+
+
+def text_summary(patches: list[dict[str, Any]], limit: int) -> dict[str, list[dict[str, Any]]]:
+    notes: Counter[str] = Counter()
+    errors: Counter[str] = Counter()
+    for patch in patches:
+        annotation = patch.get("annotation") or {}
+        note = annotation.get("notes")
+        if isinstance(note, str) and note.strip():
+            notes[note.strip()[:240]] += 1
+        for error in patch.get("errors") or []:
+            if isinstance(error, str) and error.strip():
+                errors[error.strip()[:240]] += 1
+    return {
+        "notes": [{"text": text, "count": count} for text, count in notes.most_common(limit)],
+        "errors": [{"text": text, "count": count} for text, count in errors.most_common(limit)],
+    }
+
+
+def compact_patch_stats(path: Path, label: str, summary_limit: int) -> dict[str, Any]:
+    report = validate_patches(path)
+    patches = report["valid_patches"]
+    terminals = {tid for patch in patches for tid in patch["terminal_ids"]}
+    statuses = Counter(str(patch.get("status")) for patch in patches)
+    return {
+        "label": label,
+        "path": str(path),
+        "validation": {key: value for key, value in report.items() if not key.startswith("valid_")},
+        "status_counts": {status: statuses.get(status, 0) for status in sorted(PATCH_STATUSES)},
+        "terminal_coverage_count": len(terminals),
+        "terminals": terminals,
+        "annotation_empty_rates": annotation_empty_rates(patches),
+        "text_summary": text_summary(patches, summary_limit),
+    }
+
+
+def compare_patches(
+    left_path: Path,
+    right_path: Path,
+    left_label: str,
+    right_label: str,
+    summary_limit: int,
+) -> dict[str, Any]:
+    left = compact_patch_stats(left_path, left_label, summary_limit)
+    right = compact_patch_stats(right_path, right_label, summary_limit)
+    left_terminals = left.pop("terminals")
+    right_terminals = right.pop("terminals")
+    return {
+        "schema": "dmhy_annotation_patch_comparison",
+        "schema_version": SCHEMA_VERSION,
+        "left": left,
+        "right": right,
+        "terminal_intersection_count": len(left_terminals & right_terminals),
+        "left_only_terminal_count": len(left_terminals - right_terminals),
+        "right_only_terminal_count": len(right_terminals - left_terminals),
+        "terminal_union_count": len(left_terminals | right_terminals),
+    }
+
+
+def main() -> None:
+    args = parse_args()
+    if args.command == "validate-units":
+        report = validate_units(args.units_jsonl)
+        summarize_report(report, args.manifest_output)
+        raise SystemExit(1 if report["error_count"] else 0)
+    if args.command == "validate-patches":
+        report = validate_patches(args.patches_jsonl, args.units)
+        summarize_report(report, args.manifest_output)
+        raise SystemExit(1 if report["error_count"] else 0)
+    if args.command == "compare-patches":
+        report = compare_patches(
+            args.left_patches_jsonl,
+            args.right_patches_jsonl,
+            args.left_label,
+            args.right_label,
+            max(1, args.summary_limit),
+        )
+        summarize_report(report, args.manifest_output)
+        left_errors = report["left"]["validation"]["error_count"]
+        right_errors = report["right"]["validation"]["error_count"]
+        raise SystemExit(1 if left_errors or right_errors else 0)
+    raise SystemExit(f"unknown command: {args.command}")
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except BrokenPipeError:
+        sys.exit(1)