@shundoo-ai/dsh-cosmic 1.0.19 → 1.0.21

package/skills/cosmic-build/scripts/plugin_corpus/measure_api_usage.py

@@ -0,0 +1,446 @@
+#!/usr/bin/env python3
+"""Measure how business plugins in the L0 index use the platform API.
+
+Answers the two P1 questions of the plugin corpus plan from the index built by
+``build_index.py``:
+
+1. Of the platform members business plugins reference, how many are public SDK surface?
+2. Of those public members, how many does the API knowledge (``knowledge/cosmic/platform/api``)
+   document? It also lists the most referenced public members the pages do not document, and
+   the most referenced non-public ones.
+
+Population: classes in reference-indexed layers whose class hierarchy reaches a plugin base
+class registered in ``references/type-registry.json`` (the sole type/base mapping), or that
+carry a registered class annotation, plus their nested and anonymous classes. ``--extra-root``
+adds further base classes for an ad-hoc question without changing the registry.
+
+Evidence scope:
+- A reference is a constant-pool entry naming a member. It counts classes that name the member,
+  not call sites, and it says nothing about runtime behaviour.
+- A reference is resolved to its declaring class through the indexed hierarchy. A class defined
+  more than once with different content is resolved by layer priority and reported as ambiguous.
+- Public means the declaring class carries ``@SdkPublic``, ``@SdkPlugin``, ``@SdkService`` or
+  ``@SdkSPI``, and the member does not carry ``@SdkInternal``. A member inherited from an unmarked
+  platform class through a public subclass is reported separately as ``public-inherited``.
+- A page documents a member when the declaring class's page lists that name with the same
+  parameter types. Pages carry no constructors, so constructors are reported on their own.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sqlite3
+import sys
+import time
+from collections import Counter, defaultdict
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+import jvm_classfile  # noqa: E402
+import platform_api_contract as api  # noqa: E402
+from build_index import DB_NAME  # noqa: E402
+
+PUBLIC_MARKERS = {"kd.sdk.annotation.SdkPublic", "kd.sdk.annotation.SdkPlugin",
+                  "kd.sdk.annotation.SdkService", "kd.sdk.annotation.SdkSPI"}
+INTERNAL_MARKER = "kd.sdk.annotation.SdkInternal"
+DEPRECATED_MARKERS = {"kd.sdk.annotation.SdkDeprecated", "java.lang.Deprecated"}
+DEFAULT_PLATFORM_LAYERS = ("bos",)
+# A class defined in several layers resolves to the first layer here that defines it. The
+# project's compile classpath (config.gradle) is trd, bos, biz and cus; a patch directory is an
+# overlay outside it, so it never shadows the bos definition.
+LAYER_PRIORITY = ("bos", "biz", "cus", "trd", "patch")
+_TYPE_VARIABLE_RE = re.compile(r"^[A-Z][A-Z0-9]?(\[\])*$")
+
+
+class MeasureError(RuntimeError):
+    def __init__(self, code: str, message: str):
+        super().__init__(message)
+        self.code = code
+
+
+def _registry_roots(extra_roots: list[str]) -> tuple[dict[str, str], dict[str, str]]:
+    """Base class fqcn -> registry type, and class annotation fqcn -> registry type."""
+    registry = json.loads(api.TYPE_REGISTRY_PAGE.read_text(encoding="utf-8-sig"))
+    bases: dict[str, str] = {}
+    annotations: dict[str, str] = {}
+    for entry in registry.get("types", []):
+        target = annotations if str(entry.get("baseClass") or "").startswith("@") else bases
+        for fqcn in str(entry.get("baseImport") or "").split(","):
+            if fqcn.strip():
+                target.setdefault(fqcn.strip(), entry["type"])
+    for fqcn in extra_roots:
+        bases.setdefault(fqcn, "extra-root")
+    return bases, annotations
+
+
+def _page_signatures() -> dict[str, dict[str, set[tuple[str, ...]]]]:
+    """Platform class fqcn (binary name) -> member name -> documented parameter type tuples.
+
+    Uses the same front matter and signature parsing as the source checks, so a member counts as
+    documented here exactly when those checks would find it on the page.
+    """
+    pages: dict[str, dict[str, set[tuple[str, ...]]]] = {}
+    for path in api.API_ROOT.rglob("*.md"):
+        text = path.read_text(encoding="utf-8-sig", errors="replace")
+        front = api._FRONT_MATTER_RE.search(text)
+        if not front:
+            continue
+        meta = {match.group("key"): match.group("value").strip()
+                for match in api._FRONT_MATTER_FIELD_RE.finditer(front.group("body"))}
+        simple, package = meta.get("api_class") or "", meta.get("api_package") or ""
+        if not simple or not package.startswith(api.PLATFORM_PACKAGE.rstrip(".")):
+            continue
+        # A nested class page names its outer class as the package and prefixes the class name.
+        outer, _, nested = simple.partition(".")
+        fqcn = (f"{package}${nested.replace('.', '$')}" if nested and outer == package.rpartition(".")[2]
+                else f"{package}.{simple}")
+        members = pages.setdefault(fqcn, {})
+        for match in api._SIGNATURE_RE.finditer(text):
+            members.setdefault(match.group("name"), set()).add(tuple(api._param_types(match.group("params"))))
+    return pages
+
+
+def _parameters_match(documented: tuple[str, ...], actual: list[str]) -> bool:
+    if len(documented) != len(actual):
+        return False
+    for page_type, java_type in zip(documented, actual):
+        if page_type == java_type:
+            continue
+        # A generic type variable on the page erases to a reference type in the descriptor.
+        if _TYPE_VARIABLE_RE.match(page_type) and page_type.count("[]") == java_type.count("[]") \
+                and java_type.rstrip("[]") not in jvm_classfile._PRIMITIVES.values():
+            continue
+        return False
+    return True
+
+
+class Index:
+    """Read-only view over the L0 index with hierarchy and member resolution."""
+
+    def __init__(self, db_path: Path):
+        if not db_path.is_file():
+            raise MeasureError("CORPUS_INDEX_MISSING", f"No L0 index at {db_path}; run build_index.py first")
+        self.db = sqlite3.connect(f"file:{db_path}?mode=ro", uri=True)
+        self.text = dict(self.db.execute("SELECT id, value FROM strings"))
+        self.ids = {value: key for key, value in self.text.items()}
+        rank = {layer: position for position, layer in enumerate(LAYER_PRIORITY)}
+        candidates: dict[int, list[tuple]] = defaultdict(list)
+        for row in self.db.execute(
+                "SELECT c.id, c.name_id, c.super_id, c.access, c.annotations, c.sha256, j.layer, j.refs_indexed "
+                "FROM classes c JOIN jars j ON j.id = c.jar_id"):
+            candidates[row[1]].append(row)
+        interfaces: dict[int, list[int]] = defaultdict(list)
+        for class_id, iface_id in self.db.execute("SELECT class_id, iface_id FROM interfaces"):
+            interfaces[class_id].append(iface_id)
+        # name id -> (class id, super id, interface ids, access, annotations, layer, refs_indexed, ambiguous)
+        self.classes: dict[int, tuple] = {}
+        for name_id, rows in candidates.items():
+            rows.sort(key=lambda row: (rank.get(row[6], len(rank)), row[0]))
+            chosen = rows[0]
+            ambiguous = len({row[5] for row in rows}) > 1
+            self.classes[name_id] = (chosen[0], chosen[2], interfaces.get(chosen[0], []), chosen[3],
+                                     frozenset((chosen[4] or "").split()), chosen[6], chosen[7], ambiguous)
+        self.interfaces = interfaces
+        self._members: dict[int, dict[tuple[str, int, int], frozenset[str]]] = {}
+        self._resolved: dict[tuple, tuple] = {}
+
+    def members(self, class_id: int) -> dict[tuple[str, int, int], frozenset[str]]:
+        cached = self._members.get(class_id)
+        if cached is None:
+            cached = {(kind, name_id, desc_id): frozenset((annotations or "").split())
+                      for kind, name_id, desc_id, annotations in self.db.execute(
+                          "SELECT kind, name_id, desc_id, annotations FROM members WHERE class_id=?", (class_id,))}
+            self._members[class_id] = cached
+        return cached
+
+    def resolve(self, owner_id: int, kind: str, name_id: int, desc_id: int) -> tuple:
+        """(declaring name id or None, chain from the owner to it, ambiguous, member annotations).
+
+        Methods are looked up in the class, then its superclass chain, then its interfaces;
+        fields in the class, its interfaces, then its superclass, as the JVM resolves them.
+        """
+        key = (owner_id, kind, name_id, desc_id)
+        known = self._resolved.get(key)
+        if known is not None:
+            return known
+        member_kind = "F" if kind == "F" else "M"
+        seen: set[int] = set()
+
+        def search(name: int) -> tuple[int, tuple[int, ...], bool, frozenset[str]] | None:
+            if name in seen:
+                return None
+            seen.add(name)
+            entry = self.classes.get(name)
+            if entry is None:
+                return None
+            found = self.members(entry[0]).get((member_kind, name_id, desc_id))
+            if found is not None:
+                return name, (name,), entry[7], found
+            parents = ([entry[1]] if entry[1] else []) + list(entry[2])
+            if member_kind == "F":
+                parents = list(entry[2]) + ([entry[1]] if entry[1] else [])
+            for parent in parents:
+                result = search(parent)
+                if result:
+                    return result[0], (name, *result[1]), entry[7] or result[2], result[3]
+            return None
+
+        result = search(owner_id)
+        value = result if result else (None, (), False, frozenset())
+        self._resolved[key] = value
+        return value
+
+    def nearest_base(self, name_id: int, bases: dict[int, str]) -> int | None:
+        """The registered base reached in the fewest inheritance steps, superclass before interfaces."""
+        frontier, seen = [name_id], {name_id}
+        while frontier:
+            following = []
+            for name in frontier:
+                entry = self.classes.get(name)
+                if not entry:
+                    continue
+                for parent in ([entry[1]] if entry[1] else []) + list(entry[2]):
+                    if parent in bases:
+                        return parent
+                    if parent not in seen:
+                        seen.add(parent)
+                        following.append(parent)
+            frontier = following
+        return None
+
+
+def _signature(index: Index, owner: str, kind: str, name_id: int, desc_id: int) -> str:
+    name, descriptor = index.text[name_id], index.text[desc_id]
+    params, returned = jvm_classfile.descriptor_types(descriptor)
+    if kind == "F":
+        return f"{returned} {owner}.{name}"
+    if name == "<init>":
+        return f"new {owner}({', '.join(params)})"
+    return f"{returned} {owner}.{name}({', '.join(params)})"
+
+
+def measure(workspace: str, top: int, platform_layers: list[str], extra_roots: list[str]) -> dict:
+    started = time.monotonic()
+    root = Path(workspace).expanduser().resolve()
+    index = Index(root / DB_NAME)
+    platform = set(platform_layers)
+    base_types, annotation_types = _registry_roots(extra_roots)
+    base_ids = {index.ids[fqcn]: kind for fqcn, kind in base_types.items() if fqcn in index.ids}
+    missing_bases = sorted(fqcn for fqcn in base_types if fqcn not in index.ids)
+
+    plugins: dict[int, str] = {}
+    for name_id, entry in index.classes.items():
+        if not entry[6]:
+            continue
+        base = index.nearest_base(name_id, base_ids)
+        if base is not None:
+            plugins[name_id] = base_ids[base]
+            continue
+        marker = next((annotation_types[item] for item in sorted(entry[4]) if item in annotation_types), None)
+        if marker:
+            plugins[name_id] = marker
+    top_level = {index.text[name_id]: name_id for name_id in plugins}
+    population: dict[int, int] = {}  # class id -> top-level plugin name id
+    for name_id, entry in index.classes.items():
+        if not entry[6]:
+            continue
+        outer = index.text[name_id].split("$", 1)[0]
+        if outer in top_level:
+            population[entry[0]] = top_level[outer]
+
+    by_type = Counter(plugins.values())
+    pairs = Counter()          # target layer -> (class, member) references
+    labels = Counter()
+    coverage = Counter()
+    member_classes: dict[tuple, set[int]] = defaultdict(set)
+    member_info: dict[tuple, dict] = {}
+    plugin_flags: dict[int, set[str]] = defaultdict(set)
+    ambiguous_refs = 0
+    java_refs = sum(count or 0 for class_id, count in index.db.execute("SELECT id, java_refs FROM classes")
+                    if class_id in population)
+    pages = _page_signatures()
+    for class_id, kind, owner_id, name_id, desc_id in index.db.execute(
+            "SELECT class_id, kind, owner_id, name_id, desc_id FROM refs WHERE kind IN ('M', 'I', 'F')"):
+        plugin = population.get(class_id)
+        if plugin is None:
+            continue
+        declaring, path, ambiguous, member_annotations = index.resolve(owner_id, kind, name_id, desc_id)
+        if declaring is None:
+            pairs["unresolved"] += 1
+            continue
+        entry = index.classes[declaring]
+        layer = entry[5]
+        if layer not in platform:
+            pairs[layer] += 1
+            continue
+        pairs["platform"] += 1
+        ambiguous_refs += 1 if ambiguous else 0
+        markers = entry[4]
+        chain_platform = [step for step in path if index.classes[step][5] in platform]
+        if INTERNAL_MARKER in member_annotations:
+            label = "internal"
+        elif markers & PUBLIC_MARKERS:
+            label = "public"
+        elif any(index.classes[step][4] & PUBLIC_MARKERS for step in chain_platform[:-1]):
+            label = "public-inherited"
+        elif INTERNAL_MARKER in markers:
+            label = "internal"
+        else:
+            label = "unmarked"
+        labels[label] += 1
+        plugin_flags[plugin].add(label)
+        member_name = index.text[name_id]
+        owner = index.text[declaring]
+        if label.startswith("public"):
+            if kind == "F":
+                status = "field"
+            elif member_name == "<init>":
+                status = "constructor"
+            else:
+                # Follow the chain the way describe-class does: any documented class between the
+                # referenced type and the declaring class may list the member.
+                chain_pages = [pages[index.text[step]] for step in chain_platform if index.text[step] in pages]
+                listed = [option for page in chain_pages for option in page.get(member_name, ())]
+                params = [jvm_classfile.simple_type(item)
+                          for item in jvm_classfile.descriptor_types(index.text[desc_id])[0]]
+                if not chain_pages:
+                    status = "no-page"
+                elif any(_parameters_match(option, params) for option in listed):
+                    status = "documented"
+                else:
+                    status = "overload-missing" if listed else "member-missing"
+            coverage[status] += 1
+        else:
+            status = None
+        key = (declaring, kind == "F", name_id, desc_id)
+        member_classes[key].add(class_id)
+        info = member_info.get(key)
+        if info is None:
+            member_info[key] = {"signature": _signature(index, owner.replace("$", "."), kind, name_id, desc_id),
+                                "label": label, "documentation": status,
+                                "deprecated": bool((member_annotations | markers) & DEPRECATED_MARKERS)}
+        elif status == "documented":
+            # Documented through any receiver type counts; another chain may miss the page.
+            info["documentation"] = status
+
+    def ranked(select) -> list[dict]:
+        rows = []
+        for key, classes in member_classes.items():
+            info = member_info[key]
+            if select(info):
+                plugin_names = sorted({index.text[population[class_id]] for class_id in classes})
+                rows.append({**info, "referencingClasses": len(classes), "referencingPlugins": len(plugin_names),
+                             "examplePlugins": plugin_names[:3]})
+        rows.sort(key=lambda row: (-row["referencingPlugins"], -row["referencingClasses"], row["signature"]))
+        return rows[:top]
+
+    distinct = Counter(info["label"] for info in member_info.values())
+    distinct_coverage = Counter(info["documentation"] for info in member_info.values() if info["documentation"])
+    public_total = sum(coverage.values())
+    public_methods = public_total - coverage["constructor"] - coverage["field"]
+    platform_total = pairs["platform"]
+    fully_public = sum(1 for plugin in plugins if plugin_flags.get(plugin) and
+                       plugin_flags[plugin] <= {"public", "public-inherited"})
+    with_platform = sum(1 for plugin in plugins if plugin_flags.get(plugin))
+
+    def share(part: int, whole: int) -> float | None:
+        return round(part / whole, 4) if whole else None
+
+    return {
+        "status": True,
+        "database": str(root / DB_NAME),
+        "evidenceScope": [
+            "Constant-pool references: counts classes that name a member, not call sites or runtime use.",
+            "Declaring class resolved through the indexed hierarchy; ambiguous duplicates are counted.",
+            "Public = declaring class marked SdkPublic/SdkPlugin/SdkService/SdkSPI and member not SdkInternal.",
+            "Documented = the declaring class's API page lists the name with the same parameter types.",
+        ],
+        "population": {
+            "pluginClasses": len(plugins), "classesIncludingNested": len(population),
+            "pluginClassesByRegistryType": dict(by_type.most_common()),
+            "registryBasesMissingFromIndex": missing_bases,
+            "platformLayers": sorted(platform),
+        },
+        "references": {
+            "byTargetLayer": {**dict(pairs.most_common()), "java(not stored)": java_refs},
+            "platformByLabel": dict(labels.most_common()),
+            "platformDistinctMembersByLabel": dict(distinct.most_common()),
+            "ambiguousPlatformReferences": ambiguous_refs,
+        },
+        "measurements": {
+            "publicShareOfPlatformReferences": share(labels["public"] + labels["public-inherited"], platform_total),
+            "publicShareStrict": share(labels["public"], platform_total),
+            "documentedShareOfPublicMethodReferences": share(coverage["documented"], public_methods),
+            "publicReferenceDocumentation": dict(coverage.most_common()),
+            "publicDistinctMemberDocumentation": dict(distinct_coverage.most_common()),
+            "pluginsUsingOnlyPublicPlatformMembers": fully_public,
+            "pluginsWithPlatformReferences": with_platform,
+            "pluginsUsingOnlyPublicShare": share(fully_public, with_platform),
+        },
+        "topUndocumentedPublicMembers": ranked(lambda info: info["documentation"] in
+                                               ("no-page", "member-missing", "overload-missing")),
+        "topPublicConstructors": ranked(lambda info: info["documentation"] == "constructor"),
+        "topPublicFields": ranked(lambda info: info["documentation"] == "field"),
+        "topNonPublicMembers": ranked(lambda info: info["label"] in ("internal", "unmarked")),
+        "elapsedSec": round(time.monotonic() - started, 1),
+    }
+
+
+def write_markdown(result: dict, path: Path) -> None:
+    measurements = result["measurements"]
+    references = result["references"]
+    population = result["population"]
+
+    def pct(value: float | None) -> str:
+        return "n/a" if value is None else f"{value * 100:.1f}%"
+
+    lines = [
+        "# L0 plugin corpus: platform API usage", "",
+        f"- Database: `{result['database']}`",
+        f"- Plugin classes: {population['pluginClasses']} ({population['classesIncludingNested']} with nested classes)",
+        f"- Platform references (class-member pairs): {references['byTargetLayer'].get('platform', 0)}",
+        f"- Public share of platform references: {pct(measurements['publicShareOfPlatformReferences'])}"
+        f" (strict, excluding public-inherited: {pct(measurements['publicShareStrict'])})",
+        f"- Documented share of public method references: {pct(measurements['documentedShareOfPublicMethodReferences'])}"
+        " (constructors and fields counted separately; API pages carry neither)",
+        f"- Plugins whose platform references are all public: {measurements['pluginsUsingOnlyPublicPlatformMembers']}"
+        f" of {measurements['pluginsWithPlatformReferences']} ({pct(measurements['pluginsUsingOnlyPublicShare'])})",
+        "", "Evidence scope:", "", *[f"- {item}" for item in result["evidenceScope"]], "",
+    ]
+    for title, key in (("Most referenced public members without matching API documentation", "topUndocumentedPublicMembers"),
+                       ("Most referenced public constructors (pages carry none)", "topPublicConstructors"),
+                       ("Most referenced public fields and enum constants (pages carry none)", "topPublicFields"),
+                       ("Most referenced non-public platform members", "topNonPublicMembers")):
+        lines += [f"## {title}", "", "| Plugins | Classes | Label | Documentation | Member |", "| --- | --- | --- | --- | --- |"]
+        lines += [f"| {row['referencingPlugins']} | {row['referencingClasses']} | {row['label']} | "
+                  f"{row['documentation'] or '-'} | `{row['signature']}` |" for row in result[key]]
+        lines.append("")
+    path.write_text("\n".join(lines), encoding="utf-8")
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__.split("\n\n")[0])
+    parser.add_argument("--workspace", required=True, help="Corpus workspace holding the L0 index")
+    parser.add_argument("--top", type=int, default=50, help="Rows per ranked list")
+    parser.add_argument("--platform-layer", action="append", help="Layer treated as platform (default: bos)")
+    parser.add_argument("--extra-root", action="append", default=[], help="Additional population base class fqcn")
+    args = parser.parse_args(argv)
+    try:
+        result = measure(args.workspace, args.top, args.platform_layer or list(DEFAULT_PLATFORM_LAYERS), args.extra_root)
+    except MeasureError as exc:
+        print(json.dumps({"status": False, "errorCode": exc.code, "message": str(exc)}, ensure_ascii=False))
+        return 2
+    output = Path(args.workspace).expanduser().resolve() / "measurements"
+    output.mkdir(exist_ok=True)
+    (output / "p1-api-usage.json").write_text(json.dumps(result, ensure_ascii=False, indent=2), encoding="utf-8")
+    write_markdown(result, output / "p1-api-usage.md")
+    print(json.dumps({key: result[key] for key in ("status", "population", "references", "measurements", "elapsedSec")},
+                     ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/cosmic-build/scripts/plugin_source_gate.py

@@ -11,6 +11,8 @@ from __future__ import annotations
 import argparse
 import json
 import os
+import hashlib
+import re
 from pathlib import Path
 from typing import Optional
 
@@ -27,6 +29,7 @@ def write_state(
     class_name: str,
     state: str,
     session_id: Optional[str] = None,
+    emit: bool = True,
 ) -> None:
     if state not in STATES:
         print(json.dumps({"error": f"invalid state: {state}, must be {'|'.join(STATES)}"}))
@@ -36,12 +39,13 @@ def write_state(
     Path(path).parent.mkdir(parents=True, exist_ok=True)
     content = state if not session_id else f"{state}:{session_id}"
     Path(path).write_text(content, encoding="utf-8")
-    print(json.dumps({
-        "status": "ok",
-        "file": path,
-        "state": state,
-        "session_id": session_id,
-    }))
+    if emit:
+        print(json.dumps({
+            "status": "ok",
+            "file": path,
+            "state": state,
+            "session_id": session_id,
+        }))
 
 
 def read_state(project_root: str, class_name: str) -> None:
@@ -53,13 +57,50 @@ def read_state(project_root: str, class_name: str) -> None:
     content = path.read_text(encoding="utf-8").strip()
     raw_state = content.split(":", 1)[0]
     if raw_state == "source_ready":
-        print(json.dumps({"state": raw_state, "verdict": "compile_backed_pass"}))
+        print(json.dumps({"state": raw_state, "verdict": "source_ready_only"}))
     elif raw_state == "coding":
         print(json.dumps({"state": raw_state, "verdict": "source_pending", "raw": content}))
     else:
         print(json.dumps({"state": raw_state, "verdict": "unknown"}))
 
 
+
+def validate_registration_entry(entry, target_type, class_name=None):
+    """Check the declared source and compile outcome, shared by registration entry points."""
+    class_name = class_name or str(entry.get("className") or "")
+    registry = json.loads((Path(__file__).resolve().parents[1] / "references" / "type-registry.json")
+                          .read_text(encoding="utf-8"))["types"]
+    definition = next((item for item in registry if item["type"] == entry.get("type")), None)
+    if definition is None:
+        raise ValueError("PLUGIN_LOCAL_TYPE_UNVERIFIED: archive type is not in the registry")
+    expected = definition.get("registrationTargetType")
+    if expected and expected != target_type:
+        raise ValueError("PLUGIN_REGISTRATION_TYPE_MISMATCH: archive expects " + expected
+                         + ", requested " + target_type)
+    source = Path(str(entry.get("filePath") or ""))
+    if not source.is_absolute() or not source.is_file():
+        raise ValueError("PLUGIN_LOCAL_SOURCE_UNVERIFIED: resolve the archive source path before registration")
+    from java_source import stripped
+    text = stripped(source.read_text(encoding="utf-8-sig"))
+    declaration = re.search(r"\bclass\s+" + re.escape(class_name.rsplit(".", 1)[-1])
+                            + r"\b([^{}]*)\{", text)
+    if declaration is None:
+        raise ValueError("PLUGIN_LOCAL_CLASS_UNVERIFIED: class declaration missing from archive source")
+    base = re.search(r"\bextends\s+([\w.]+)", declaration.group(1))
+    if definition.get("baseClass") and base is None and "implements" not in declaration.group(1):
+        raise ValueError("PLUGIN_SOURCE_BASE_CLASS_MISSING: plain Java class is not a registered plugin")
+    known = next((item for item in registry if base and item.get("baseClass") == base.group(1).rsplit(".", 1)[-1]), None)
+    if known and known.get("registrationTargetType") != target_type:
+        raise ValueError("PLUGIN_SOURCE_TARGET_MISMATCH: declared plugin base does not match registration target")
+
+    if entry.get("compileStatus") not in {"passed", "skipped-by-config"}:
+        raise ValueError("PLUGIN_SOURCE_NOT_READY: run compile_plugin_source.py; manual archive writes are not compile evidence")
+    actual = hashlib.sha256(source.read_bytes()).hexdigest()
+    if entry.get("sourceHash") != actual:
+        raise ValueError("PLUGIN_SOURCE_CHANGED: source differs from its compile result; compile the current source again")
+    return {"compileStatus": entry["compileStatus"], "sourceHash": actual}
+
+
 def main() -> None:
     parser = argparse.ArgumentParser(description="Java plugin source delivery gate")
     parser.add_argument(

package/skills/cosmic-build/scripts/plugin_target_sdk.py

@@ -0,0 +1,45 @@
+"""Verify the bound module and selected SDK declarations before source generation."""
+from pathlib import Path
+
+from compile_plugin_source import inspect_compile_environment
+from inspect_platform_sdk import inspect_sdk
+
+
+class TargetSdkError(ValueError):
+    def __init__(self, code, message):
+        super().__init__(message)
+        self.error_code = code
+
+
+def verify_target_sdk(project_root, coding, usage=None):
+    environment = inspect_compile_environment(project_root)
+    if environment.get('status') == 'disabled':
+        return {'status': 'not-run', 'compile': False, 'projectRoot': str(Path(project_root).resolve()),
+                'evidenceScope': 'Source-only configuration: target SDK, compilation and runtime are unverified'}
+    if environment.get('status') != 'ready':
+        raise TargetSdkError(environment.get('code') or 'PLUGIN_SDK_ENVIRONMENT_UNVERIFIED',
+                             environment.get('message') or 'Target compile environment is unverified')
+    jars = sorted({str(file.resolve()) for directory in environment.get('sdkDirectories', [])
+                   for file in Path(directory['path']).glob('*.jar')})
+    if not jars:
+        raise TargetSdkError('PLUGIN_TARGET_SDK_UNRESOLVED', 'The bound module does not establish target SDK libraries')
+    if usage is not None and (not isinstance(usage, list) or any(not isinstance(item, dict)
+            or not isinstance(item.get('class'), str) or not item['class']
+            or set(item) - {'class', 'members'} or not isinstance(item.get('members', []), list)
+            or any(not isinstance(member, str) or not member for member in item.get('members', [])) for item in usage)):
+        raise TargetSdkError('PLUGIN_SDK_USAGE_INVALID', 'sdkUsage requires exact class and member selectors')
+    classes = sorted({coding.get('baseContract', {}).get('class'),
+                      *[item.get('class') for item in coding.get('signatureTypes', [])]} - {None})
+    verified = [inspect_sdk(jars, name, mode='locate') for name in classes if name.startswith('kd.bos.')]
+    contracts = [inspect_sdk(jars, item['class'], item.get('members')) for item in usage or []]
+    for result in [*verified, *contracts]:
+        if result.get('status') is not True:
+            raise TargetSdkError(result.get('errorCode') or 'PLUGIN_TARGET_SDK_UNVERIFIED', result.get('message') or 'Target SDK verification failed')
+        if result.get('missingDeclaredMembers'):
+            raise TargetSdkError('PLUGIN_SDK_MEMBER_UNVERIFIED',
+                                 f"{result['class']}: members not declared in the target SDK: {result['missingDeclaredMembers']}; verify an inherited declaration separately")
+    return {'status': 'verified', 'projectRoot': str(Path(project_root).resolve()),
+            'gradleRoot': environment['gradleRoot'], 'module': environment['module'],
+            'javaHome': environment['javaHome'], 'sdkDirectories': environment['sdkDirectories'],
+            'classes': verified, 'contracts': contracts,
+            'evidenceScope': 'Bound module, target SDK class identities and selected declarations; no compilation or runtime behavior is implied'}