cseq 0.0.1__py3-none-any.whl

cseq/parser_contract_cases.json

@@ -0,0 +1,69 @@
+{
+  "schema_version": 1,
+  "purpose": "G2B Tree-sitter Fast Syntax Front-end acceptance corpus",
+  "cases": [
+    {
+      "id": "TS-01-basic-direct-call",
+      "source": "static int add1(int x){return x+1;} int main(void){return add1(1);}",
+      "required_node_types": [
+        "function_definition",
+        "call_expression",
+        "return_statement"
+      ],
+      "must_not_require_semantic_refinement": true
+    },
+    {
+      "id": "TS-02-control-structure",
+      "source": "int f(int x){if(x){while(x--){;} } else {for(;;){break;}} return x;}",
+      "required_node_types": [
+        "function_definition",
+        "if_statement",
+        "while_statement",
+        "for_statement",
+        "break_statement"
+      ],
+      "must_not_require_semantic_refinement": true
+    },
+    {
+      "id": "TS-03-typedef-struct",
+      "source": "typedef struct Ctx { int value; } Ctx; int f(Ctx *c){return c->value;}",
+      "required_node_types": [
+        "type_definition",
+        "struct_specifier",
+        "field_expression"
+      ],
+      "must_not_require_semantic_refinement": false,
+      "refinement_reason": "TYPE_AMBIGUOUS"
+    },
+    {
+      "id": "TS-04-preprocessor",
+      "source": "#ifdef FEATURE_X\nint f(void){return 1;}\n#else\nint f(void){return 0;}\n#endif\n",
+      "required_node_types": [
+        "preproc_ifdef",
+        "function_definition"
+      ],
+      "must_preserve_all_branches": true
+    },
+    {
+      "id": "TS-05-error-recovery",
+      "source": "int good(void){return 1;} int broken( { int after(void){return 2;}",
+      "required_node_types": [],
+      "must_report_error_or_missing_node": true,
+      "must_preserve_recoverable_regions": true,
+      "expected_parse_status_any_of": [
+        "ERROR_RECOVERED",
+        "PARTIAL"
+      ],
+      "minimum_recovered_functions": 1
+    },
+    {
+      "id": "TS-06-vendor-extension",
+      "source": "__vendor_magic int helper(void){return 1;} int main(void){return helper();}",
+      "required_node_types": [
+        "translation_unit"
+      ],
+      "must_require_semantic_refinement": true,
+      "refinement_reason": "COMPILER_EXTENSION"
+    }
+  ]
+}

cseq/parser_dependency_lock.json

@@ -0,0 +1,59 @@
+{
+  "schema_version": 1,
+  "decision_id": "ADR-001",
+  "canonical_frontend": "tree-sitter-c",
+  "packages": {
+    "tree-sitter": {
+      "version": "0.26.0",
+      "python_requires": ">=3.10",
+      "artifacts": {
+        "cp313-linux-x86_64-glibc": {
+          "filename": "tree_sitter-0.26.0-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl",
+          "sha256": "7075ef857ef86f327dbb72d1e2574dda78db5754b3a1fca6506acd7fe5d561a7"
+        },
+        "cp313-windows-x86_64": {
+          "filename": "tree_sitter-0.26.0-cp313-cp313-win_amd64.whl",
+          "sha256": "93e220cab7e6a823efeb2046c49171427de92ef71c7c681c01820d14d8d3721f"
+        },
+        "cp311-linux-x86_64-glibc": {
+          "filename": "tree_sitter-0.26.0-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl",
+          "sha256": "335294ce0504fcefde5245dff596778ffaf820205b98ae0b549c72e48855f1d8"
+        },
+        "cp311-windows-x86_64": {
+          "filename": "tree_sitter-0.26.0-cp311-cp311-win_amd64.whl",
+          "sha256": "0f8793fd18ad7eec276ed4b51c097b4bf2002b357259b66b0d75db1f3f41c754"
+        },
+        "cp312-linux-x86_64-glibc": {
+          "filename": "tree_sitter-0.26.0-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl",
+          "sha256": "5a6b333b0282d8bb0af741f9b018bd2523d4eecb2686bf6717066a625fecfaa4"
+        },
+        "cp312-windows-x86_64": {
+          "filename": "tree_sitter-0.26.0-cp312-cp312-win_amd64.whl",
+          "sha256": "ca89e361a276dbc934b28a43dd881199e25d34ff5493ee0ce45f3c52a6124a37"
+        }
+      }
+    },
+    "tree-sitter-c": {
+      "version": "0.24.2",
+      "python_requires": ">=3.10",
+      "grammar_abi": 15,
+      "artifacts": {
+        "abi3-linux-x86_64-glibc": {
+          "filename": "tree_sitter_c-0.24.2-cp310-abi3-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl",
+          "sha256": "5041ef67eb68ce6bc8bb0b1f8ef3a5585ce523dae0c7eec109ab0627dd75aede"
+        },
+        "abi3-windows-x86_64": {
+          "filename": "tree_sitter_c-0.24.2-cp310-abi3-win_amd64.whl",
+          "sha256": "abb549225091f7b25df2dd3a0143ece6e208f7055d8bcb4700b41ee79b9ef1e1"
+        }
+      }
+    }
+  },
+  "expected_api": {
+    "language_factory": "tree_sitter.Language(tree_sitter_c.language())",
+    "parser_factory": "tree_sitter.Parser(language)",
+    "parse_call": "parser.parse(source_bytes)",
+    "smoke_source": "int main(void) { return 0; }",
+    "smoke_root_type": "translation_unit"
+  }
+}

cseq/parser_environment.py

@@ -0,0 +1,186 @@
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from importlib import metadata, util
+import json
+from pathlib import Path
+import platform
+import sys
+from typing import Any
+
+
+_LOCK_PATH = Path(__file__).with_name("parser_dependency_lock.json")
+
+
+@dataclass(frozen=True)
+class ParserEnvironment:
+    tree_sitter_available: bool
+    tree_sitter_c_available: bool
+    tree_sitter_version: str | None
+    tree_sitter_c_version: str | None
+    expected_tree_sitter_version: str
+    expected_tree_sitter_c_version: str
+    versions_match_lock: bool
+    api_smoke_tested: bool
+    api_smoke_ok: bool | None
+    grammar_abi: int | None
+    expected_grammar_abi: int
+    grammar_abi_match: bool | None
+    platform_lock_key: str | None
+    runtime_wheel_filename: str | None
+    runtime_wheel_sha256: str | None
+    grammar_wheel_filename: str | None
+    grammar_wheel_sha256: str | None
+    canonical_fast_frontend_ready: bool
+    fallback_required: bool
+    incompatibility_reasons: tuple[str, ...]
+
+    def to_dict(self) -> dict[str, object]:
+        return asdict(self)
+
+
+def load_parser_dependency_lock() -> dict[str, Any]:
+    return json.loads(_LOCK_PATH.read_text(encoding="utf-8"))
+
+
+def _distribution_version(name: str) -> str | None:
+    try:
+        return metadata.version(name)
+    except metadata.PackageNotFoundError:
+        return None
+
+
+def _platform_keys() -> tuple[str | None, str | None]:
+    machine = platform.machine().lower()
+    if machine in {"amd64", "x86_64"}:
+        arch = "x86_64"
+    elif machine in {"arm64", "aarch64"}:
+        arch = "aarch64"
+    else:
+        arch = machine
+    py = f"cp{sys.version_info.major}{sys.version_info.minor}"
+    system = platform.system().lower()
+    if system == "linux":
+        return f"{py}-linux-{arch}-glibc", f"abi3-linux-{arch}-glibc"
+    if system == "windows":
+        return f"{py}-windows-{arch}", f"abi3-windows-{arch}"
+    return None, None
+
+
+def _artifact(lock: dict[str, Any], package: str, key: str | None) -> tuple[str | None, str | None]:
+    if key is None:
+        return None, None
+    entry = lock["packages"][package].get("artifacts", {}).get(key)
+    if not entry:
+        return None, None
+    return entry.get("filename"), entry.get("sha256")
+
+
+def _smoke_tree_sitter(expected_abi: int, smoke_source: str, smoke_root: str) -> tuple[bool, int | None, str | None]:
+    """Import the locked API and execute a minimal C parse.
+
+    The function is called only when both distributions are discoverable.  Any
+    native/API incompatibility becomes a diagnostic reason rather than leaking
+    an import exception out of `cseq doctor`.
+    """
+    try:
+        import tree_sitter  # type: ignore
+        import tree_sitter_c  # type: ignore
+
+        language = tree_sitter.Language(tree_sitter_c.language())
+        abi = int(getattr(language, "abi_version"))
+        parser = tree_sitter.Parser(language)
+        tree = parser.parse(smoke_source.encode("utf-8"))
+        root_type = getattr(tree.root_node, "type", None)
+        ok = abi == expected_abi and root_type == smoke_root
+        reason = None if ok else f"smoke-mismatch: abi={abi}, root={root_type!r}"
+        return ok, abi, reason
+    except Exception as exc:  # pragma: no cover - depends on native runtime
+        return False, None, f"api-smoke-failed: {type(exc).__name__}: {exc}"
+
+
+def probe_parser_environment() -> ParserEnvironment:
+    """Inspect the parser runtime against the G2 dependency lock.
+
+    Availability alone is insufficient. Canonical readiness requires the exact
+    locked distribution versions plus a real API/grammar smoke parse.  Missing
+    dependencies and incompatible installed dependencies are therefore reported
+    as distinct states by the returned diagnostics.
+    """
+    lock = load_parser_dependency_lock()
+    ts_lock = lock["packages"]["tree-sitter"]
+    c_lock = lock["packages"]["tree-sitter-c"]
+    expected_ts = str(ts_lock["version"])
+    expected_c = str(c_lock["version"])
+    expected_abi = int(c_lock["grammar_abi"])
+
+    ts = util.find_spec("tree_sitter") is not None
+    tsc = util.find_spec("tree_sitter_c") is not None
+    ts_version = _distribution_version("tree-sitter") if ts else None
+    c_version = _distribution_version("tree-sitter-c") if tsc else None
+    versions_match = ts_version == expected_ts and c_version == expected_c
+
+    runtime_key, grammar_key = _platform_keys()
+    runtime_filename, runtime_hash = _artifact(lock, "tree-sitter", runtime_key)
+    grammar_filename, grammar_hash = _artifact(lock, "tree-sitter-c", grammar_key)
+
+    reasons: list[str] = []
+    if not ts:
+        reasons.append("tree-sitter-not-installed")
+    if not tsc:
+        reasons.append("tree-sitter-c-not-installed")
+    if ts and ts_version != expected_ts:
+        reasons.append(f"tree-sitter-version-mismatch:{ts_version}!={expected_ts}")
+    if tsc and c_version != expected_c:
+        reasons.append(f"tree-sitter-c-version-mismatch:{c_version}!={expected_c}")
+    if runtime_key is not None and runtime_filename is None:
+        reasons.append(f"runtime-wheel-not-locked-for:{runtime_key}")
+    if grammar_key is not None and grammar_filename is None:
+        reasons.append(f"grammar-wheel-not-locked-for:{grammar_key}")
+
+    smoke_tested = bool(ts and tsc and versions_match)
+    smoke_ok: bool | None = None
+    grammar_abi: int | None = None
+    grammar_abi_match: bool | None = None
+    if smoke_tested:
+        smoke_ok, grammar_abi, smoke_reason = _smoke_tree_sitter(
+            expected_abi,
+            str(lock["expected_api"]["smoke_source"]),
+            str(lock["expected_api"]["smoke_root_type"]),
+        )
+        grammar_abi_match = grammar_abi == expected_abi if grammar_abi is not None else False
+        if smoke_reason:
+            reasons.append(smoke_reason)
+
+    ready = bool(
+        ts
+        and tsc
+        and versions_match
+        and smoke_tested
+        and smoke_ok
+        and grammar_abi_match
+        and runtime_filename
+        and grammar_filename
+    )
+    return ParserEnvironment(
+        tree_sitter_available=ts,
+        tree_sitter_c_available=tsc,
+        tree_sitter_version=ts_version,
+        tree_sitter_c_version=c_version,
+        expected_tree_sitter_version=expected_ts,
+        expected_tree_sitter_c_version=expected_c,
+        versions_match_lock=versions_match,
+        api_smoke_tested=smoke_tested,
+        api_smoke_ok=smoke_ok,
+        grammar_abi=grammar_abi,
+        expected_grammar_abi=expected_abi,
+        grammar_abi_match=grammar_abi_match,
+        platform_lock_key=runtime_key,
+        runtime_wheel_filename=runtime_filename,
+        runtime_wheel_sha256=runtime_hash,
+        grammar_wheel_filename=grammar_filename,
+        grammar_wheel_sha256=grammar_hash,
+        canonical_fast_frontend_ready=ready,
+        fallback_required=not ready,
+        incompatibility_reasons=tuple(reasons),
+    )

cseq/parser_migration.py

@@ -0,0 +1,126 @@
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+import hashlib
+import json
+from pathlib import Path
+from typing import Any
+
+from .parser_environment import load_parser_dependency_lock, probe_parser_environment
+
+
+_CONTRACT_PATH = Path(__file__).with_name("parser_contract_cases.json")
+
+
+@dataclass(frozen=True)
+class WheelArtifactCheck:
+    package: str
+    filename: str | None
+    expected_sha256: str | None
+    path: str | None
+    exists: bool
+    actual_sha256: str | None
+    hash_match: bool
+
+    def to_dict(self) -> dict[str, object]:
+        return asdict(self)
+
+
+@dataclass(frozen=True)
+class G2BResumeReport:
+    status: str
+    environment_ready: bool
+    wheelhouse_checked: bool
+    wheelhouse_ready: bool | None
+    wheel_checks: tuple[WheelArtifactCheck, ...]
+    contract_case_count: int
+    next_action: str
+
+    def to_dict(self) -> dict[str, object]:
+        payload = asdict(self)
+        payload["wheel_checks"] = [item.to_dict() for item in self.wheel_checks]
+        return payload
+
+
+def _sha256(path: Path) -> str:
+    h = hashlib.sha256()
+    with path.open("rb") as f:
+        for chunk in iter(lambda: f.read(1024 * 1024), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def load_parser_contract_cases() -> tuple[dict[str, Any], ...]:
+    raw = json.loads(_CONTRACT_PATH.read_text(encoding="utf-8"))
+    cases = raw.get("cases", [])
+    if not isinstance(cases, list):
+        raise ValueError("parser contract cases must be a list")
+    return tuple(cases)
+
+
+def verify_parser_wheelhouse(directory: str | Path) -> tuple[WheelArtifactCheck, ...]:
+    """Verify the exact locked wheels required by the current platform.
+
+    This deliberately does not install anything. It makes the G2B restart
+    condition deterministic and safe for offline/corporate environments.
+    """
+    root = Path(directory)
+    env = probe_parser_environment()
+    required = (
+        ("tree-sitter", env.runtime_wheel_filename, env.runtime_wheel_sha256),
+        ("tree-sitter-c", env.grammar_wheel_filename, env.grammar_wheel_sha256),
+    )
+    checks: list[WheelArtifactCheck] = []
+    for package, filename, expected in required:
+        if filename is None or expected is None:
+            checks.append(WheelArtifactCheck(package, filename, expected, None, False, None, False))
+            continue
+        path = root / filename
+        exists = path.is_file()
+        actual = _sha256(path) if exists else None
+        checks.append(WheelArtifactCheck(
+            package=package,
+            filename=filename,
+            expected_sha256=expected,
+            path=str(path),
+            exists=exists,
+            actual_sha256=actual,
+            hash_match=bool(exists and actual == expected),
+        ))
+    return tuple(checks)
+
+
+def build_g2b_resume_report(wheel_dir: str | Path | None = None) -> G2BResumeReport:
+    env = probe_parser_environment()
+    contract_count = len(load_parser_contract_cases())
+    if env.canonical_fast_frontend_ready:
+        return G2BResumeReport(
+            status="READY_FOR_TREE_SITTER_EXECUTION",
+            environment_ready=True,
+            wheelhouse_checked=wheel_dir is not None,
+            wheelhouse_ready=None if wheel_dir is None else all(x.hash_match for x in verify_parser_wheelhouse(wheel_dir)),
+            wheel_checks=() if wheel_dir is None else verify_parser_wheelhouse(wheel_dir),
+            contract_case_count=contract_count,
+            next_action="run-cseq-analysis",
+        )
+
+    checks = () if wheel_dir is None else verify_parser_wheelhouse(wheel_dir)
+    wheel_ready = None if wheel_dir is None else bool(checks and all(x.hash_match for x in checks))
+    if wheel_ready:
+        next_action = "offline-install-locked-wheels-then-rerun-doctor"
+        status = "WHEELS_VERIFIED_INSTALL_REQUIRED"
+    elif wheel_dir is not None:
+        next_action = "supply-exact-locked-wheels"
+        status = "WHEELHOUSE_INCOMPLETE_OR_MISMATCHED"
+    else:
+        next_action = "supply-locked-wheelhouse-or-install-locked-runtime"
+        status = "DEPENDENCY_BLOCKED"
+    return G2BResumeReport(
+        status=status,
+        environment_ready=False,
+        wheelhouse_checked=wheel_dir is not None,
+        wheelhouse_ready=wheel_ready,
+        wheel_checks=checks,
+        contract_case_count=contract_count,
+        next_action=next_action,
+    )

cseq/plugin.py

@@ -0,0 +1,216 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from importlib import metadata
+from typing import Any, Iterable, Protocol, runtime_checkable
+
+from .model import CallSiteRecord, FunctionRecord
+from .runtime import RuntimeEvent
+
+PLUGIN_API_VERSION = 1
+ENTRY_POINT_GROUP = "cseq.plugins"
+
+
+class PluginKind(str, Enum):
+    COMPILER_EXTENSION = "CompilerExtensionPlugin"
+    CPU_RULE_PROVIDER = "CpuRuleProvider"
+    SEMANTIC_HINT_PROVIDER = "SemanticHintProvider"
+    RUNTIME_TIMESTAMP_PARSER = "RuntimeTimestampParser"
+    RUNTIME_EVENT_PROVIDER = "RuntimeEventProvider"
+    LINKER_MAP_ADAPTER = "LinkerMapAdapter"
+    RENDERER_EXTENSION = "RendererExtension"
+
+
+@dataclass(frozen=True, slots=True)
+class FunctionView:
+    name: str
+    qualified_id: str
+    source_path: str
+    storage_class: str | None
+    parameters: tuple[str, ...]
+
+    @classmethod
+    def from_record(cls, record: FunctionRecord) -> "FunctionView":
+        return cls(record.name, record.qualified_id, record.source_path, record.storage_class, record.parameters)
+
+
+@dataclass(frozen=True, slots=True)
+class CallSiteView:
+    caller_id: str
+    caller_name: str
+    callee_name: str | None
+    raw_text: str
+    source_path: str
+    target_kind: str
+    target_function_ids: tuple[str, ...]
+    unknown_possible: bool
+
+    @classmethod
+    def from_record(cls, record: CallSiteRecord) -> "CallSiteView":
+        return cls(
+            record.caller_id,
+            record.caller_name,
+            record.callee_name,
+            record.raw_text,
+            record.source_path,
+            record.target_kind.value,
+            record.target_function_ids,
+            record.unknown_possible,
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class RuntimeEventView:
+    event_index: int
+    marker_id: str
+    timestamp_raw: str | None
+    cpu_hint: str | None
+    task_hint: str | None
+    message: str | None
+    payload: tuple[tuple[str, str], ...]
+
+    @classmethod
+    def from_record(cls, record: RuntimeEvent) -> "RuntimeEventView":
+        return cls(
+            record.event_index,
+            record.marker_id,
+            record.timestamp_raw,
+            record.cpu_hint,
+            record.task_hint,
+            record.message,
+            record.payload,
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class PluginEvidence:
+    plugin_name: str
+    kind: PluginKind
+    target: str
+    evidence_type: str
+    value: str
+    confidence: str = "MEDIUM"
+    details: tuple[tuple[str, str], ...] = ()
+
+
+@dataclass(frozen=True, slots=True)
+class PluginDiagnostic:
+    plugin_name: str
+    severity: str
+    code: str
+    message: str
+
+
+@dataclass(frozen=True, slots=True)
+class PluginDescriptor:
+    name: str
+    kinds: tuple[PluginKind, ...]
+    api_version: int = PLUGIN_API_VERSION
+    version: str | None = None
+
+
+@runtime_checkable
+class CseqPlugin(Protocol):
+    descriptor: PluginDescriptor
+
+
+@dataclass(slots=True)
+class PluginRunResult:
+    evidence: list[PluginEvidence] = field(default_factory=list)
+    diagnostics: list[PluginDiagnostic] = field(default_factory=list)
+
+    @property
+    def has_errors(self) -> bool:
+        return any(d.severity in {"error", "fatal"} for d in self.diagnostics)
+
+
+class PluginManager:
+    """Fail-safe plugin executor.
+
+    Plugins receive immutable façade views rather than internal IR objects. Any
+    plugin exception becomes a diagnostic; the core caller can continue with
+    ordinary analysis and simply lose the extra evidence.
+    """
+
+    def __init__(self, plugins: Iterable[CseqPlugin] = ()):
+        self._plugins: dict[str, CseqPlugin] = {}
+        self.diagnostics: list[PluginDiagnostic] = []
+        for plugin in plugins:
+            self.register(plugin)
+
+    @property
+    def plugins(self) -> tuple[CseqPlugin, ...]:
+        return tuple(self._plugins[name] for name in sorted(self._plugins))
+
+    def register(self, plugin: CseqPlugin) -> None:
+        descriptor = getattr(plugin, "descriptor", None)
+        if not isinstance(descriptor, PluginDescriptor):
+            raise TypeError("plugin must expose PluginDescriptor as descriptor")
+        if descriptor.api_version != PLUGIN_API_VERSION:
+            raise ValueError(
+                f"plugin {descriptor.name} API {descriptor.api_version} is incompatible with cseq API {PLUGIN_API_VERSION}"
+            )
+        self._plugins[descriptor.name] = plugin
+
+    @classmethod
+    def discover(cls, enabled: Iterable[str] | None = None) -> "PluginManager":
+        enabled_set = set(enabled or ())
+        manager = cls()
+        try:
+            eps = metadata.entry_points()
+            group = eps.select(group=ENTRY_POINT_GROUP) if hasattr(eps, "select") else eps.get(ENTRY_POINT_GROUP, [])
+        except Exception as exc:  # discovery itself must not kill core analysis
+            manager.diagnostics.append(PluginDiagnostic("<discovery>", "warning", "PLUGIN_DISCOVERY_FAILED", str(exc)))
+            return manager
+        discovered_names: set[str] = set()
+        for ep in group:
+            discovered_names.add(ep.name)
+            if enabled_set and ep.name not in enabled_set:
+                continue
+            try:
+                obj = ep.load()
+                plugin = obj() if isinstance(obj, type) else obj
+                manager.register(plugin)
+            except Exception as exc:
+                manager.diagnostics.append(PluginDiagnostic(ep.name, "warning", "PLUGIN_LOAD_FAILED", str(exc)))
+        for missing in sorted(enabled_set - discovered_names):
+            manager.diagnostics.append(PluginDiagnostic(missing, "warning", "PLUGIN_NOT_FOUND", "enabled plugin was not discovered"))
+        return manager
+
+    def run_semantic_hints(
+        self,
+        *,
+        functions: Iterable[FunctionRecord] = (),
+        callsites: Iterable[CallSiteRecord] = (),
+    ) -> PluginRunResult:
+        fviews = tuple(FunctionView.from_record(x) for x in functions)
+        cviews = tuple(CallSiteView.from_record(x) for x in callsites)
+        return self._run_hook("semantic_hints", functions=fviews, callsites=cviews)
+
+    def run_runtime_event_hints(self, events: Iterable[RuntimeEvent]) -> PluginRunResult:
+        views = tuple(RuntimeEventView.from_record(x) for x in events)
+        return self._run_hook("runtime_event_hints", events=views)
+
+    def _run_hook(self, hook: str, **kwargs: Any) -> PluginRunResult:
+        result = PluginRunResult(diagnostics=list(self.diagnostics))
+        for plugin in self.plugins:
+            fn = getattr(plugin, hook, None)
+            if fn is None:
+                continue
+            name = plugin.descriptor.name
+            try:
+                returned = fn(**kwargs)
+                if returned is None:
+                    continue
+                for item in returned:
+                    if not isinstance(item, PluginEvidence):
+                        raise TypeError(f"{hook} must yield PluginEvidence, got {type(item).__name__}")
+                    if item.plugin_name != name:
+                        raise ValueError("PluginEvidence.plugin_name must match plugin descriptor name")
+                    if item.kind not in plugin.descriptor.kinds:
+                        raise ValueError(f"evidence kind {item.kind.value} was not declared by plugin")
+                    result.evidence.append(item)
+            except Exception as exc:
+                result.diagnostics.append(PluginDiagnostic(name, "warning", "PLUGIN_HOOK_FAILED", f"{hook}: {exc}"))
+        return result