@shundoo-ai/dsh-cosmic 1.0.19 → 1.0.21

package/skills/cosmic-build/scripts/test/test_guide_skeleton_contract.py

@@ -1,23 +1,20 @@
-"""A plugin type is defined in three places that nothing checked against each other.
-
-`references/type-registry.json` is the authority — "downstream docs and prompts should resolve
-per-type behavior from this registry". `cosmic-coding-impl`'s mapping table resolves the same
-classSuffix and guide independently, and each guide's `## Skeleton Template` states which type it
-serves. Every drift below reached delivery: `report-plugin` carried one suffix in the table and
-another in the registry, the registry sent the three mobile types to a guide with no skeleton at
-all, four guides declared a type name the registry does not have, and form-plugin.md used
-`EventObject` in five places while its import block never named it.
-
-Every check is narrow on purpose. A guess at what counts as a drift reports a finding nobody can
-fix, and a false finding here blocks delivery while a missed one costs one compile round.
-"""
+"""The type registry drives coding evidence and each guide's supported skeletons."""
 
 import json
+import os
 import re
+import shutil
+import subprocess
+import sys
 from pathlib import Path
 
+import pytest
+
 
 ROOT = Path(__file__).resolve().parents[2]
+# Target SDK JARs (bos and trd) joined with the path separator. The compile check below runs only
+# when it is set; javac comes from JAVA_HOME when set, otherwise PATH, and must accept -source 8.
+SDK_CLASSPATH = os.environ.get("COSMIC_SDK_PLUGIN_CLASSPATH", "")
 # This file is byte-identical in both skill trees, so it must work from either: the locale tree has
 # no nested locale tree. From the English root both are checked, from the zh root only that one.
 TREES = [ROOT] + [tree for tree in [ROOT / ".locales" / "zh"] if tree.is_dir()]
@@ -48,8 +45,6 @@ _DECLARED_TYPES_RE = re.compile(
     r"(?:Applicable to|Applies to|适用于|适用)\s*[:：]\s*((?:`[\w-]+`(?:\s*/\s*)?)+)")
 _BACKTICKED_RE = re.compile(r"`([\w-]+)`")
 _STATED_SUFFIX_RE = re.compile(r"(?:suffix follows|类名后缀按)\s*`([A-Za-z{][\w{}]*)`")
-_TABLE_ROW_RE = re.compile(r"^\|\s*`([\w-]+)`\s*\|\s*`([A-Za-z]\w*)`\s*\|\s*(.+?)\s*\|\s*$",
-                           re.MULTILINE)
 
 
 def _registry(tree):
@@ -59,17 +54,10 @@ def _registry(tree):
 
 
 def _guides(tree):
-    """Every distinct guide a type points at. `service` publishes none by design — the mapping
-    table records "no guide; every required API needs exact documentation" for it."""
+    """Every distinct guide a type points at; service has no guide."""
     return sorted({entry["guide"] for entry in _registry(tree).values() if entry.get("guide")})
 
 
-def _mapping_table(tree):
-    """type -> (classSuffix, guide) as cosmic-coding-impl's own table declares them."""
-    text = (tree / "skills" / "cosmic-coding-impl" / "SKILL.md").read_text(encoding="utf-8")
-    return {name: (suffix, guide.strip("`")) for name, suffix, guide in _TABLE_ROW_RE.findall(text)}
-
-
 def _skeletons(tree, guide):
     """The java blocks under the skeleton heading that declare a type.
 
@@ -109,26 +97,27 @@ def test_a_guide_declares_the_type_name_the_registry_uses():
     assert not findings, "guides naming a type absent from the registry: " + "; ".join(findings)
 
 
-def test_the_mapping_table_and_the_registry_agree_on_every_type():
-    """Alias types stay in both places on purpose: `form_plugin` is dispatched by formtemplate and
-    dynamic_form_emit, so dropping it from the table would break those two paths."""
+def test_coding_evidence_resolves_every_registered_type_without_a_second_mapping():
     for tree in TREES:
-        registry, table = _registry(tree), _mapping_table(tree)
-
-        assert table, f"{tree.name}: the plugin mapping table parsed as empty"
-        assert set(table) == set(registry), (
-            f"{tree.name}: table only: {sorted(set(table) - set(registry))}, "
-            f"registry only: {sorted(set(registry) - set(table))}"
+        result = subprocess.run(
+            [sys.executable, "-c",
+             "import json; from platform_api_contract import plugin_coding_evidence, TYPE_REGISTRY_PAGE; "
+             "entries=json.loads(TYPE_REGISTRY_PAGE.read_text())['types']; "
+             "print(json.dumps({e['type']:plugin_coding_evidence(e['type']) for e in entries}))"],
+            cwd=tree / "scripts", capture_output=True, text=True, check=True,
         )
-        suffix_drift = {name: (suffix, registry[name]["classSuffix"])
-                        for name, (suffix, _) in table.items()
-                        if suffix != registry[name]["classSuffix"]}
-        guide_drift = {name: (guide, registry[name]["guide"])
-                       for name, (_, guide) in table.items()
-                       if registry[name].get("guide") and not guide.endswith(registry[name]["guide"])}
-
-        assert not suffix_drift, f"{tree.name}: classSuffix (table, registry): {suffix_drift}"
-        assert not guide_drift, f"{tree.name}: guide (table, registry): {guide_drift}"
+        evidence = json.loads(result.stdout)
+        for name, entry in _registry(tree).items():
+            actual = evidence[name]
+            if entry.get("guide"):
+                assert Path(actual["guide"]).resolve() == (tree / entry["guide"]).resolve()
+                assert Path(actual["guide"]).is_file()
+            else:
+                assert actual["guide"] is None
+            if entry.get("baseImport"):
+                assert actual["baseContract"]["class"] == entry["baseImport"]
+            assert Path(actual["typeKnowledge"]).is_file()
+            assert Path(actual["standards"]).is_file()
 
 
 def test_a_guide_does_not_hardcode_a_class_suffix_that_contradicts_the_registry():
@@ -155,8 +144,7 @@ def test_a_guide_does_not_hardcode_a_class_suffix_that_contradicts_the_registry(
 
 
 def test_no_skeleton_uses_a_jdk_type_it_does_not_import():
-    """cosmic-coding-impl requires every imported class to trace to a page read in that run, so a
-    skeleton using a type it never imports leaves the correct import with no legal source."""
+    """A usable skeleton must import each non-implicit JDK type it uses."""
     findings = []
     for tree in TREES:
         for guide in _guides(tree):
@@ -183,3 +171,59 @@ def test_only_the_one_known_guide_publishes_no_skeleton():
 
     assert without == sorted(f"{tree.name}:knowledge/cosmic/platform/task-plugin.md"
                              for tree in TREES), without
+
+
+def _javac():
+    home = os.environ.get("JAVA_HOME")
+    candidate = Path(home) / "bin" / ("javac.exe" if os.name == "nt" else "javac") if home else None
+    return str(candidate) if candidate and candidate.is_file() else shutil.which("javac")
+
+
+def _instantiated(entry, block):
+    """The skeleton as the coding step fills it for one registry type.
+
+    The placeholder table tells the coding step to substitute the registry's suffix and base class
+    and to import that base; package placeholders become a fixed sample package.
+    """
+    base = entry["baseImport"]
+    source = block.replace("{PluginSuffix}", entry["classSuffix"]).replace("{BaseClass}", base.rsplit(".", 1)[-1])
+    source = re.sub(r"\{\w+\}", "sample", source)
+    if "{BaseClass}" in block:
+        source = re.sub(r"^(package [^;]+;)", rf"\1\nimport {base};", source, count=1, flags=re.MULTILINE)
+    return source
+
+
+@pytest.mark.skipif(not SDK_CLASSPATH or not _javac(), reason="target SDK classpath or javac unavailable")
+def test_every_skeleton_compiles_against_the_target_sdk(tmp_path):
+    """The coding step copies a skeleton's imports and event signatures as verified evidence, and
+    the API pages cannot prove a skeleton right: list-plugin.md imported two event classes that do
+    not exist (`ListPackageDataEvent`, `PrepareFilterEvent`), form-plugin.md and list-plugin.md
+    imported `ShowType` from a package that does not exist, the shared form skeleton overrode
+    `afterLoadData` that only bill bases declare, and the workflow skeleton called `super` on
+    interface methods. Each compiled nowhere; only the target SDK shows it."""
+    failures = []
+    for tree in TREES:
+        seen = set()
+        for entry in _registry(tree).values():
+            base = str(entry.get("baseImport") or "")
+            if not entry.get("guide") or not base or "," in base or str(entry.get("baseClass", "")).startswith("@"):
+                continue
+            blocks = _skeletons(tree, entry["guide"])
+            if not blocks or (entry["guide"], base) in seen:
+                continue
+            seen.add((entry["guide"], base))
+            source = _instantiated(entry, blocks[0])
+            name = re.search(r"^\s*public\s+(?:(?:abstract|final)\s+)*(?:class|interface)\s+(\w+)",
+                             source, re.MULTILINE).group(1)
+            work = tmp_path / f"{tree.name}-{entry['type']}"
+            (work / "classes").mkdir(parents=True)
+            (work / f"{name}.java").write_text(source, encoding="utf-8")
+            result = subprocess.run(
+                [_javac(), "-J-Duser.language=en", "-source", "8", "-target", "8", "-proc:none", "-nowarn",
+                 "-encoding", "UTF-8", "-cp", SDK_CLASSPATH, "-d", str(work / "classes"), str(work / f"{name}.java")],
+                capture_output=True, text=True)
+            if result.returncode:
+                errors = re.findall(r"\.java:\d+: error: .*", result.stderr) or [result.stderr.strip()[:300]]
+                failures.append(f"{tree.name}:{entry['guide']} as {entry['type']}: " + "; ".join(errors[:3]))
+
+    assert not failures, "skeletons that do not compile against the target SDK:\n" + "\n".join(failures)

package/skills/cosmic-build/scripts/test/test_inspect_platform_sdk.py

@@ -0,0 +1,71 @@
+import hashlib
+import json
+import shutil
+import subprocess
+import sys
+import zipfile
+from pathlib import Path
+
+import pytest
+
+SCRIPT = Path(__file__).resolve().parents[1] / "inspect_platform_sdk.py"
+
+
+@pytest.fixture
+def sdk(tmp_path):
+    if not shutil.which("javac") or not shutil.which("javap"):
+        pytest.skip("JDK tools unavailable")
+    source = tmp_path / "Target.java"
+    source.write_text('package sample; public class Target { public String getOperationKey() { return "unit.operation"; } }')
+    subprocess.run(["javac", "-d", str(tmp_path), str(source)], check=True, capture_output=True)
+    jar = tmp_path / "sdk.jar"
+    with zipfile.ZipFile(jar, "w") as archive:
+        archive.write(tmp_path / "sample/Target.class", "sample/Target.class")
+        archive.writestr("META-INF/MANIFEST.MF", "Manifest-Version: 1.0\nImplementation-Version: test-1\n")
+        archive.writestr("sample/Target.java", source.read_text())
+    return jar
+
+
+def query(jar, *args):
+    result = subprocess.run([sys.executable, str(SCRIPT), "--jar", str(jar), *args],
+                            capture_output=True, text=True)
+    return result.returncode, json.loads(result.stdout)
+
+
+def test_sdk_inspection_uses_real_class_declarations_and_selected_bytecode(sdk):
+    code, result = query(sdk, "--class", "Target", "--member", "getOperationKey")
+    assert code == 0
+    assert result["class"] == "sample.Target"
+    assert result["version"] == "test-1"
+    assert result["jarSha256"] == hashlib.sha256(sdk.read_bytes()).hexdigest()
+    assert result["members"][0]["declaration"] == "public java.lang.String getOperationKey();"
+    assert result["missingDeclaredMembers"] == []
+    code, result = query(sdk, "--class", "sample.Target", "--member", "getOperationKey", "--mode", "bytecode")
+    assert code == 0
+    assert any("unit.operation" in line for line in result["members"][0]["details"])
+    assert len(result["members"]) == 1
+
+
+def test_sdk_lookup_does_not_guess_a_duplicate_version_or_an_absent_method(sdk, tmp_path):
+    other = tmp_path / "duplicate.jar"
+    shutil.copyfile(sdk, other)
+    code, result = query(sdk, "--jar", str(other), "--class", "sample.Target")
+    assert code == 2 and result["errorCode"] == "SDK_CLASS_AMBIGUOUS"
+    assert len(result["candidates"]) == 2
+    code, result = query(sdk, "--class", "sample.Target", "--member", "notDeclared")
+    assert code == 0
+    assert result["members"] == [] and result["missingDeclaredMembers"] == ["notDeclared"]
+    code, result = query(sdk, "--class", "Missing")
+    assert code == 2 and result["errorCode"] == "SDK_CLASS_NOT_FOUND"
+    code, result = query(sdk, "--class", "sample.Target", "--mode", "bytecode")
+    assert code == 2 and result["errorCode"] == "SDK_MEMBER_REQUIRED"
+
+
+def test_reference_jars_are_read_by_exact_entry_without_extracting_files(sdk):
+    code, result = query(sdk, "--list-resources", "Target")
+    assert code == 0 and result["items"][0]["resource"] == "sample/Target.java"
+    code, result = query(sdk, "--resource", "sample/Target.java", "--limit", "1")
+    assert code == 0 and "public class Target" in result["content"]
+    assert result["resourceSha256"] and result["lineCount"] == 1
+    code, result = query(sdk, "--resource", "sample/Target.class")
+    assert code == 2 and result["errorCode"] == "SDK_REFERENCE_NOT_UNIQUE"

package/skills/cosmic-build/scripts/test/test_kd_api.py

@@ -1,12 +1,12 @@
 #!/usr/bin/env python3
-"""Tests for kd_api.py — 业务 facade 入口。
-
-覆盖：
-  - _resolve_base：base_url 解析优先级 / 缺失报错
-  - post / get：URL 拼接、body/query 构造、header 风格、timeout 透传
-  - _request_once：HTTP 401 / body 业务码 401 → TokenExpiredError 归一化；其它 HTTPError 原样上抛
-  - _call_with_retry：成功不刷新；TokenExpiredError 强刷重试一次；连续两次失败仍上抛
-  - invalidate_cache：委托 kd_token_cache.invalidate(None)
+"""Tests for kd_api.py — business facade entry point.
+
+Coverage:
+  - _resolve_base: base_url resolution priority / missing error
+  - post / get: URL construction, body/query building, header style, timeout passthrough
+  - _request_once: HTTP 401 / body business code 401 -> TokenExpiredError normalization; other HTTPError re-raised as-is
+  - _call_with_retry: success no refresh; TokenExpiredError force refresh retry once; consecutive two failures still re-raised
+  - invalidate_cache: delegates to kd_token_cache.invalidate(None)
 """
 from __future__ import annotations
 
@@ -26,13 +26,13 @@ import kd_api
 import kd_auth
 
 
-# ─── 测试替身：替换 _http_client.retry_call ──────────────────────────────
+# ─── Test doubles: replace _http_client.retry_call ──────────────────────────────
 
 def _fake_retry(*behaviors):
-    """构造一个 retry_call 替身。
+    """Construct a retry_call double.
 
-    behaviors: 每次调用的 (response, exc) 二元组；超出长度时复用最后一个。
-    返回 (callable, calls) ——calls 记录每次调用的 (fn_name, args, kwargs)。
+    behaviors: (response, exc) tuple for each call; reuse the last when exceeding length.
+    Returns (callable, calls) — calls records (fn_name, args, kwargs) for each invocation.
     """
     calls = []
 
@@ -163,7 +163,7 @@ class GetTest(unittest.TestCase):
         self.assertEqual(args[0], "https://x/g")
 
 
-# ─── _request_once：401 归一化 ────────────────────────────────────────────
+# ─── _request_once：401 normalization ────────────────────────────────────────────
 
 class RequestOnceAuthTest(unittest.TestCase):
     def _call(self, cfg, retry_fake):
@@ -187,7 +187,7 @@ class RequestOnceAuthTest(unittest.TestCase):
             self._call(cfg, retry)
 
     def test_body_errorcode_401_raises_token_expired(self):
-        """HTTP 200 + body errorCode=401 也要归一化为 TokenExpiredError。"""
+        """HTTP 200 + body errorCode=401 should also be normalized to TokenExpiredError."""
         cfg = {"baseUrl": "https://x"}
         retry, _ = _fake_retry(({"errorCode": "401"}, None))
         with self.assertRaises(kd_auth.TokenExpiredError):
@@ -200,7 +200,7 @@ class RequestOnceAuthTest(unittest.TestCase):
         self.assertEqual(resp, {"errorCode": "500"})
 
 
-# ─── _call_with_retry：强刷重试 ──────────────────────────────────────────
+# ─── _call_with_retry：force refresh retry ──────────────────────────────────────────
 
 class CallWithRetryTest(unittest.TestCase):
     def test_success_no_force_refresh(self):
@@ -212,14 +212,14 @@ class CallWithRetryTest(unittest.TestCase):
             resp = kd_api.post(None, "/p", cfg, {})
         self.assertEqual(resp, {"ok": True})
         self.assertEqual(m_get.call_count, 1)
-        # 第一次：get_token(cfg, base)，不带 force
+        # first call: get_token(cfg, base), without force
         args, kwargs = m_get.call_args
         self.assertEqual(args, (cfg, "https://x"))
         self.assertFalse(kwargs.get("force"))
 
     def test_force_refresh_on_token_expired(self):
         cfg = {"baseUrl": "https://x"}
-        # 第一次请求抛 TokenExpiredError（body 401），第二次成功
+        # first request raises TokenExpiredError (body 401), second succeeds
         retry, _ = _fake_retry(
             (None, kd_auth.TokenExpiredError("expired")),
             ({"ok": True}, None),
@@ -230,7 +230,7 @@ class CallWithRetryTest(unittest.TestCase):
             resp = kd_api.post(None, "/p", cfg, {})
         self.assertEqual(resp, {"ok": True})
         self.assertEqual(m_get.call_count, 2)
-        # 第二次必须带 force=True
+        # second call must have force=True
         _, kwargs = m_get.call_args
         self.assertTrue(kwargs.get("force"))
 
@@ -267,7 +267,7 @@ class InvalidateCacheTest(unittest.TestCase):
         m_inv.assert_called_once_with(None)
 
     def test_config_arg_currently_ignored(self):
-        """当前实现忽略 config，统一 invalidate(None)。"""
+        """Current implementation ignores config, uniformly invalidate(None)."""
         import kd_token_cache
         with mock.patch.object(kd_token_cache, "invalidate") as m_inv:
             kd_api.invalidate_cache({"baseUrl": "https://x"})
@@ -276,3 +276,51 @@ class InvalidateCacheTest(unittest.TestCase):
 
 if __name__ == "__main__":
     unittest.main()
+
+
+class WriteTransportBoundaryTest(unittest.TestCase):
+    def test_lost_post_response_is_not_replayed_but_get_can_retry(self):
+        import http.client
+        import socket
+        import threading
+        from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+        hits = {"POST": 0, "GET": 0}
+
+        class Handler(BaseHTTPRequestHandler):
+            def log_message(self, *args):
+                pass
+
+            def do_POST(self):
+                self.rfile.read(int(self.headers.get("Content-Length", "0")))
+                hits["POST"] += 1
+                self.connection.shutdown(socket.SHUT_RDWR)
+                self.connection.close()
+
+            def do_GET(self):
+                hits["GET"] += 1
+                if hits["GET"] == 1:
+                    self.connection.shutdown(socket.SHUT_RDWR)
+                    self.connection.close()
+                    return
+                body = b'{"status":true,"data":[]}'
+                self.send_response(200)
+                self.send_header("Content-Length", str(len(body)))
+                self.end_headers()
+                self.wfile.write(body)
+
+        server = ThreadingHTTPServer(("127.0.0.1", 0), Handler)
+        worker = threading.Thread(target=server.serve_forever, daemon=True)
+        worker.start()
+        try:
+            with mock.patch.object(_http_client, "_RETRY_DELAY", 0):
+                url = f"http://127.0.0.1:{server.server_port}/write"
+                with self.assertRaises(http.client.RemoteDisconnected):
+                    kd_api._request_once(url, {}, "fixture", method="POST", body={}, params=None, style="kapi")
+                self.assertEqual(hits["POST"], 1)
+                result = kd_api._request_once(url, {}, "fixture", method="GET", body=None, params=None, style="kapi")
+                self.assertTrue(result["status"])
+                self.assertEqual(hits["GET"], 2)
+        finally:
+            server.shutdown()
+            server.server_close()
+            worker.join()

package/skills/cosmic-build/scripts/test/test_kingscript_sdk_sync.py

@@ -0,0 +1,221 @@
+import json
+import sys
+import time
+import zipfile
+from pathlib import Path
+
+import pytest
+
+SCRIPTS = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(SCRIPTS))
+
+import kingscript_sdk_sync as sdk_sync  # noqa: E402
+
+
+PKG_FILE = (
+    "export declare type AbstractFormPlugin = $.kd.bos.form.plugin.AbstractFormPlugin;\n"
+    "export declare const AbstractFormPlugin: $.kd.bos.form.plugin.AbstractFormPlugin_C;\n"
+    "export declare type AbstractMobFormPlugin = $.kd.bos.form.plugin.AbstractMobFormPlugin;\n"
+    "export declare interface AfterBindDataArgs { }\n"
+    "export declare const FormUtil: $.kd.bos.form.plugin.FormUtil_C;\n"
+    "export declare const enum Color { Red }\n"
+)
+NESTED_PKG_FILE = (
+    "/// <reference types=\"../../index\" />\n"
+    "export declare type QFilter = $.kd.bos.orm.query.QFilter;\n"
+)
+AGGREGATE_FILE = (
+    "declare global {\n"
+    "    namespace $ {\n"
+    "        namespace kd.bos.form.plugin {\n"
+    "            interface AbstractFormPlugin$ {\n"
+    "                afterBindData?(e: any): void;\n"
+    "            }\n"
+    "        }\n"
+    "    }\n"
+    "}\n"
+)
+
+
+def _make_zip(path: Path) -> Path:
+    with zipfile.ZipFile(path, "w") as bundle:
+        bundle.writestr("@cosmic/", "")
+        bundle.writestr("@cosmic/bos-core/", "")
+        bundle.writestr("@cosmic/bos-core/kd/bos/form/plugin.d.ts", PKG_FILE)
+        bundle.writestr("@cosmic/bos-core/kd/bos/orm/query.d.ts", NESTED_PKG_FILE)
+        bundle.writestr("@cosmic/bos-core/bos-form-core.d.ts", AGGREGATE_FILE)
+        bundle.writestr("@cosmic/bos-script/java/math.d.ts",
+                        "export declare type BigDecimal = $.java.math.BigDecimal;\n")
+    return path
+
+
+# ─── type index build ─────────────────────────────────────────────────────────
+
+def test_build_type_index_extracts_all_exports_per_package_file(tmp_path):
+    rows, dts_count = sdk_sync.build_type_index(_make_zip(tmp_path / "sdk.zip"))
+    by_type = {row.split("\t")[0]: row.split("\t") for row in rows}
+    # MULTILINE regression guard: every export line of a package file must be
+    # indexed, not just the first one.
+    assert by_type["AbstractFormPlugin"] == [
+        "AbstractFormPlugin", "@cosmic/bos-core", "kd/bos/form/plugin", "kd.bos.form.plugin"]
+    assert by_type["AbstractMobFormPlugin"][3] == "kd.bos.form.plugin"
+    # interface declarations and const-only value exports are importable names
+    # and must be indexed too (HttpClient-style exports on real environments).
+    assert by_type["AfterBindDataArgs"][2] == "kd/bos/form/plugin"
+    assert by_type["FormUtil"][1] == "@cosmic/bos-core"
+    # same-name type + const pair yields exactly one row (per-file dedup)
+    assert sum(1 for row in rows if row.startswith("AbstractFormPlugin\t")) == 1
+    # `export declare const enum X` must not leak the keyword as a name
+    assert "Color" not in by_type and "enum" not in by_type
+    assert by_type["QFilter"][2] == "kd/bos/orm/query"
+    assert by_type["BigDecimal"] == [
+        "BigDecimal", "@cosmic/bos-script", "java/math", "java.math"]
+    assert dts_count == 4
+
+
+def test_build_type_index_skips_module_root_aggregates(tmp_path):
+    rows, _ = sdk_sync.build_type_index(_make_zip(tmp_path / "sdk.zip"))
+    types = {row.split("\t")[0] for row in rows}
+    assert types == {"AbstractFormPlugin", "AbstractMobFormPlugin", "QFilter",
+                     "BigDecimal", "AfterBindDataArgs", "FormUtil"}
+    # the aggregate declares interfaces, never `export declare` rows
+    assert all("AbstractFormPlugin$" not in t for t in types)
+
+
+# ─── zip member safety ────────────────────────────────────────────────────────
+
+def test_safe_member_name_rejects_traversal():
+    for bad in ("../evil.d.ts", "a/../../evil.d.ts", "/abs/evil.d.ts", "C:/evil.d.ts"):
+        with pytest.raises(RuntimeError):
+            sdk_sync._safe_member_name(bad)
+
+
+def test_safe_member_name_normalizes_segments():
+    assert sdk_sync._safe_member_name("a//b/./c.d.ts") == "a/b/c.d.ts"
+    assert sdk_sync._safe_member_name("kd/bos/form/") == "kd/bos/form"
+
+
+# ─── cache state / TTL ────────────────────────────────────────────────────────
+
+def _write_cache_with_age(cache: Path, age_hours: float, types: int = 10) -> None:
+    cache.mkdir(parents=True, exist_ok=True)
+    (cache / "sdk-meta.json").write_text(json.dumps({
+        "generatedAt": int(time.time() - age_hours * 3600),
+        "envName": cache.name, "baseUrl": "https://unit.test/ierp",
+        "modules": 1, "dtsFiles": 2, "types": types,
+    }), encoding="utf-8")
+    (cache / "type-index.tsv").write_text("X\t@m/a\ta/b\ta.b\n", encoding="utf-8")
+
+
+def test_cache_state_missing(tmp_path):
+    state = sdk_sync._cache_state(tmp_path / "none", 168)
+    assert state["state"] == "missing"
+
+
+def test_cache_state_fresh_and_stale_boundary(tmp_path):
+    cache = tmp_path / "env"
+    _write_cache_with_age(cache, age_hours=2)
+    assert sdk_sync._cache_state(cache, 168)["state"] == "fresh"
+    assert sdk_sync._cache_state(cache, 1)["state"] == "stale"
+
+
+def test_cache_state_survives_corrupt_meta(tmp_path):
+    cache = tmp_path / "env"
+    cache.mkdir(parents=True)
+    (cache / "sdk-meta.json").write_text("{ not json", encoding="utf-8")
+    assert sdk_sync._cache_state(cache, 168)["state"] == "missing"
+
+
+# ─── lookup ───────────────────────────────────────────────────────────────────
+
+def test_lookup_found_and_miss(tmp_path, capsys):
+    cache = tmp_path / "env"
+    _write_cache_with_age(cache, age_hours=0)
+    lines = "A\t@m/x\tx/a\tx.a\nA\t@m/y\ty/a\ty.a\nB\t@m/x\tx/b\tx.b\n"
+    (cache / "type-index.tsv").write_text(lines, encoding="utf-8")
+    monkey = pytest.MonkeyPatch()
+    monkey.setattr(sdk_sync, "_cache_dir", lambda env: cache)
+    try:
+        assert sdk_sync.do_lookup("env", "A") == 0
+        found = json.loads(capsys.readouterr().out)
+        assert found["status"] == "found"
+        assert len(found["matches"]) == 2
+        assert found["matches"][0]["packageDot"] == "x.a"
+        assert sdk_sync.do_lookup("env", "B") == 0
+        capsys.readouterr()  # drain the intermediate output
+        assert sdk_sync.do_lookup("env", "Missing") == 2
+        miss = json.loads(capsys.readouterr().out)
+        assert miss["status"] == "miss"
+    finally:
+        monkey.undo()
+
+
+def test_lookup_without_cache_fails(tmp_path, capsys):
+    monkey = pytest.MonkeyPatch()
+    monkey.setattr(sdk_sync, "_cache_dir", lambda env: tmp_path / "empty")
+    try:
+        assert sdk_sync.do_lookup("env", "A") == 2
+        result = json.loads(capsys.readouterr().out)
+        assert result["errorCode"] == "KINGSCRIPT_SDK_CACHE_MISSING"
+    finally:
+        monkey.undo()
+
+
+# ─── ensure ───────────────────────────────────────────────────────────────────
+
+def test_ensure_skips_sync_when_fresh(tmp_path, monkeypatch, capsys):
+    cache = tmp_path / "env"
+    _write_cache_with_age(cache, age_hours=1)
+    monkeypatch.setattr(sdk_sync, "_cache_dir", lambda env: cache)
+
+    def _boom(*_args, **_kwargs):
+        raise AssertionError("sync must not run when cache is fresh")
+
+    monkeypatch.setattr(sdk_sync, "do_sync", _boom)
+    assert sdk_sync.do_ensure(server={}, env={"envName": "env"}, ttl_hours=168) == 0
+    result = json.loads(capsys.readouterr().out)
+    assert result["status"] == "ready"
+
+
+def test_ensure_triggers_sync_when_missing(tmp_path, monkeypatch):
+    monkeypatch.setattr(sdk_sync, "_cache_dir", lambda env: tmp_path / "none")
+    calls = []
+    monkeypatch.setattr(sdk_sync, "do_sync",
+                        lambda server, env: (calls.append(env), 0)[1])
+    assert sdk_sync.do_ensure(server={}, env={"envName": "env"}, ttl_hours=168) == 0
+    assert calls == [{"envName": "env"}]
+
+
+# ─── cache write ──────────────────────────────────────────────────────────────
+
+def test_write_cache_swaps_atomically_and_reports_counts(tmp_path, monkeypatch):
+    zip_path = _make_zip(tmp_path / "sdk.zip")
+    monkeypatch.setattr(sdk_sync, "SDK_ROOT", tmp_path / "sdkroot")
+    cache = tmp_path / "sdkroot" / "env"
+    cache.parent.mkdir(parents=True)
+    _write_cache_with_age(cache, age_hours=999, types=1)  # stale old cache
+    meta = sdk_sync._write_cache(cache, zip_path, {"envName": "env"},
+                                 {"baseUrl": "https://unit.test/ierp"}, "deadbeef")
+    assert meta["types"] == 6
+    assert meta["modules"] == 2
+    assert meta["dtsFiles"] == 4
+    assert meta["zipSha256"] == "deadbeef"
+    # old .old backup is gone, new index and dts tree are in place
+    assert not (tmp_path / "sdkroot" / "env.old").exists()
+    assert (cache / "type-index.tsv").read_text(encoding="utf-8").count("\n") == 6
+    assert (cache / "dts" / "@cosmic" / "bos-core" / "kd" / "bos" / "form" /
+            "plugin.d.ts").is_file()
+    # meta json is valid and carries identity
+    stored = json.loads((cache / "sdk-meta.json").read_text(encoding="utf-8"))
+    assert stored["baseUrl"] == "https://unit.test/ierp"
+    assert stored["envName"] == "env"
+
+
+def test_write_cache_creates_from_scratch(tmp_path, monkeypatch):
+    zip_path = _make_zip(tmp_path / "sdk.zip")
+    cache = tmp_path / "sdkroot" / "fresh-env"
+    cache.parent.mkdir(parents=True)
+    meta = sdk_sync._write_cache(cache, zip_path, {"envName": "fresh-env"},
+                                 {"baseUrl": "https://unit.test/ierp"}, "abc")
+    assert meta["types"] == 6
+    assert (cache / "dts" / "@cosmic" / "bos-script" / "java" / "math.d.ts").is_file()

package/skills/cosmic-build/scripts/test/test_kingscript_source_gate.py

@@ -43,6 +43,16 @@ def test_clean_plugin_passes():
     assert "KS-EXPORT-CONTRACT" not in _warn_rules(result)
 
 
+def test_kwc_controller_uses_its_native_export_binding():
+    source = "class CoffeeController {}\nlet kwcController = new CoffeeController(); export { kwcController };"
+    result = _static(source, target_type="KWC_CONTROLLER")
+    assert result["status"] is True
+    assert "KS-EXPORT-CONTRACT" not in _warn_rules(result)
+    wrong = _static(CLEAN_PLUGIN, target_type="KWC_CONTROLLER")
+    assert "KS-EXPORT-CONTRACT" in _warn_rules(wrong)
+    assert "kwcController" in next(x["message"] for x in wrong["warnings"] if x["rule"] == "KS-EXPORT-CONTRACT")
+
+
 def test_empty_content_is_blocked():
     result = _static("   ")
     assert result["status"] is False