@shundoo-ai/dsh-cosmic 1.0.19 → 1.0.21

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

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""Compile verified emit artifacts into the only payload a coding agent receives."""
+"""Prepare current native form context for Java coding, with optional legacy artifact inputs."""
 
 from __future__ import annotations
 
@@ -7,11 +7,17 @@ import argparse
 import difflib
 import json
 import re
+import subprocess
+import sys
+import uuid
 from pathlib import Path
 from typing import Any
 
-from java_source import method_signatures
+from java_source import method_signatures, stripped
 from resolve_output_path import resolve_output_path
+from platform_api_contract import plugin_coding_evidence
+
+COSMIC_API = Path(__file__).resolve().parents[1] / "skills" / "cosmic-meta-api" / "scripts" / "cosmic_api.py"
 
 
 CLASS_RE = re.compile(r"^[A-Za-z][A-Za-z0-9]*$")
@@ -38,16 +44,41 @@ def _read_json(path: str | Path) -> Any:
         raise HandoffError(f"cannot read JSON {target}: {exc}") from exc
 
 
+def manifest_artifacts(manifest_path: str) -> list[str]:
+    """Use the exact emit receipt; never search for timestamped artifact names."""
+    manifest = _read_json(manifest_path)
+    items = manifest.get("artifacts") if isinstance(manifest, dict) else None
+    if not isinstance(items, list) or not items:
+        raise HandoffError("emit manifest must contain non-empty artifacts", "PLUGIN_MANIFEST_INVALID")
+    paths = []
+    for item in items:
+        value = item.get("path") if isinstance(item, dict) else None
+        if not isinstance(value, str) or not value:
+            raise HandoffError("emit manifest artifact is missing its path", "PLUGIN_MANIFEST_INVALID")
+        target = Path(value).expanduser()
+        paths.append(str((target if target.is_absolute() else Path(manifest_path).resolve().parent / target).resolve()))
+    return paths
+
+
+def _artifact_external_catalog(entities: list[dict], fields: list[dict]) -> list[dict]:
+    """Reuse native verified emit evidence for entities already in this delivery."""
+    return [{
+        "formNumber": entity["formNumber"], "formName": entity["formName"],
+        "entityKey": entity["entityKey"], "entityName": entity["entityName"],
+        "fields": {field["fieldKey"]: {key: field.get(key) for key in ("fieldKey", "fieldName", "fieldType", "refEntity", "comboOptions")}
+                   for field in fields if field["formNumber"] == entity["formNumber"] and field["entityKey"] == entity["entityKey"]},
+    } for entity in entities]
+
+
 def _exact_one(records: list[dict], selector: str, keys: tuple[str, ...], kind: str) -> dict:
     value = str(selector or "").strip()
     matches = [row for row in records if any(str(row.get(key) or "") == value for key in keys)]
     if len(matches) != 1:
         examples = []
-        for row in records:
-            candidate = str(
-                row.get("entityName") or row.get("fieldName")
-                or row.get("authoringId") or ""
-            ).strip()
+        for row in matches or records:
+            candidate = (str(row.get("entityKey") or "") + "." + str(row["fieldKey"])
+                         + " (" + str(row.get("fieldName") or "") + ")" if row.get("fieldKey")
+                         else str(row.get("entityKey") or row.get("entityName") or row.get("authoringId") or ""))
             if candidate and candidate not in examples:
                 examples.append(candidate)
             if len(examples) == 8:
@@ -161,8 +192,6 @@ def _compile_report_contract(artifact: dict, form_number: str) -> dict | None:
     column presentation or a non-persisted filter requirement that reaches Java delivery as
     nothing is exactly how those requirements used to disappear.
     """
-    import sys
-
     scripts = Path(__file__).resolve().parents[1] / "skills" / "cosmic-meta-api" / "scripts"
     if str(scripts) not in sys.path:
         sys.path.insert(0, str(scripts))
@@ -269,6 +298,11 @@ def _catalog(
                 "entityName": entity_name,
                 "entityId": entity.get("id"),
                 "authoringId": entity.get("id"),
+                "entityType": entity.get("type"),
+                "role": "header" if entity is main else "subentries" if entity.get("type") == "SubEntryEntity" else "entries",
+                "parentEntityKey": next((row.get("entityKey") for row in authored_entities
+                    if row.get("id") == entity.get("parentEntityId")), None),
+                "collectionProperty": entity_key if entity is not main else None,
             }
             entities.append(entity_row)
             authored_fields = list(entity.get("fields") or [])
@@ -307,6 +341,7 @@ def _catalog(
                     # database ("type=DynamicObject") rather than in Java.
                     "fieldType": str(field.get("dataType") or "").strip(),
                     "refEntity": str(field.get("basedataNumber") or "").strip(),
+                    "comboOptions": field.get("comboOptions") or [],
                 })
     return forms, entities, fields, registered_plugins
 
@@ -316,12 +351,19 @@ def _scope(records: list[dict], selector: dict, *, form_keys: tuple[str, ...]) -
     if selector.get("form"):
         value = str(selector["form"]).strip()
         scoped = [row for row in scoped if any(str(row.get(key) or "") == value for key in form_keys)]
+        if not scoped:
+            raise HandoffError("form scope " + repr(value) + " is unknown; candidates: "
+                + ", ".join(sorted({str(row.get("formNumber") or "") for row in records})))
     if selector.get("entity"):
         value = str(selector["entity"]).strip()
+        candidates = scoped
         scoped = [row for row in scoped if value in (
             str(row.get("entityName") or ""), str(row.get("entityKey") or ""),
             str(row.get("entityId") or ""), str(row.get("authoringId") or ""),
-        )]
+        ) or value in {"header", "entries", "subentries"} and row.get("role") == value]
+        if not scoped:
+            raise HandoffError("entity scope " + repr(value) + " is unknown; candidates: "
+                + ", ".join(sorted({str(row.get("entityKey") or "") for row in candidates})))
     return scoped
 
 
@@ -331,6 +373,10 @@ def _resolve_entity(records: list[dict], selector: Any) -> dict:
     if not isinstance(selector, dict) or not selector.get("entity"):
         raise HandoffError("entity selector must be a string or {form, entity}")
     scoped = _scope(records, selector, form_keys=("formName", "formNumber"))
+    if selector["entity"] in {"header", "entries", "subentries"}:
+        if len(scoped) == 1:
+            return scoped[0]
+        raise HandoffError("entity scope is ambiguous; candidates: " + ", ".join(row["entityKey"] for row in scoped))
     return _exact_one(scoped, selector["entity"], ("entityName", "entityKey", "entityId", "authoringId"), "entity")
 
 
@@ -383,6 +429,8 @@ _IMPLICIT_ENTITY_FIELDS = {"id", "masterid", "seq"}
 # Cosmic field type -> the Java type its value carries. Only the families that carry the bug this
 # verification exists to stop are mapped: a reference field holds the referenced record's id, and
 # reading that as a String is what produced "operator does not exist: bigint = character varying".
+# The target 8.0 SDK's TimeProp.getPropertyType() is Integer. It stores seconds after midnight;
+# DynamicObject.getDate() converts that Integer to null, silently skipping interval checks.
 # Everything else keeps its verbatim fieldType and no javaType, because a plausible-looking guess
 # here would carry the same authority as a verified one.
 _FIELD_JAVA_TYPES = (
@@ -411,6 +459,9 @@ def _field_java_type(field_type: str) -> str | None:
     # A Mul* field holds a collection, not one value, so the single-value mapping does not apply.
     if field_type.startswith("Mul"):
         return None
+    # Match the exact time-only types: DateTimeField also contains "TimeField" as a suffix.
+    if field_type in ("TimeProp", "TimeField"):
+        return "Integer"
     for marker, java_type in _FIELD_JAVA_TYPES:
         if marker.lower() in field_type.lower():
             return java_type
@@ -443,15 +494,23 @@ def _field_contract(row: dict) -> dict | None:
         "fieldKey": field_key,
         "fieldName": str(row.get("fieldName") or "").strip(),
         "fieldType": field_type,
+        **{key: row[key] for key in ("entityKey", "entityName", "parentEntityKey", "collectionPath", "fieldPath", "required") if key in row},
     }
     if row.get("refEntity"):
         contract["refEntity"] = row["refEntity"]
+    if row.get("comboOptions"):
+        contract["comboOptions"] = row["comboOptions"]
     java_type = _field_java_type(field_type)
     if java_type:
         contract["javaType"] = java_type
-    if _is_reference_field(field_type):
+    if field_type in ("TimeProp", "TimeField"):
+        contract["valueAccessor"] = f'getInt("{field_key}")'
+        contract["timeValueUnit"] = "seconds-after-midnight"
+    reference = (bool(row.get("refEntity") or row.get("refIdProperty"))
+                 if field_type.endswith("Prop") else _is_reference_field(field_type))
+    if reference and not field_type.startswith("Mul"):
         contract["valueAccessor"] = f'getDynamicObject("{field_key}")'
-        contract["idAccessor"] = f'getLong("{field_key}_id")'
+        contract["idAccessor"] = f'getLong("{row.get("refIdProperty") or field_key + "_id"}")'
         contract["filterValue"] = f'getDynamicObject("{field_key}").getPkValue()'
         contract["note"] = (
             f'get("{field_key}") returns the referenced DynamicObject, not its id. A QFilter on '
@@ -587,6 +646,15 @@ def _verify_external_contracts(contracts: list, catalog: list[dict]) -> list:
     Returns the same list with each verified entry enriched by ``verifiedFields``, so the
     coding step receives the real key and its Java value type instead of rediscovering both.
     """
+    missing = list(dict.fromkeys(str(entry["entity"]).strip() for entry in contracts
+        if isinstance(entry, dict) and entry.get("entity")
+        and not _external_scope(catalog, str(entry["entity"]))))
+    if missing:
+        raise HandoffError(
+            "external contract entities/forms are not verified: " + ", ".join(missing)
+            + "; supply exact getFormSchema read-backs via --external-schema or use verified batch evidence",
+            "PLUGIN_EXTERNAL_CONTRACT_UNVERIFIED",
+        )
     verified: list = []
     for entry in contracts:
         if not isinstance(entry, dict):
@@ -597,13 +665,6 @@ def _verify_external_contracts(contracts: list, catalog: list[dict]) -> list:
             verified.append(entry)
             continue
         scope = _external_scope(catalog, entity_selector)
-        if not scope:
-            raise HandoffError(
-                f"external contract entity/form {entity_selector!r} is not verified; save its "
-                "exact form read-back with cosmic_api.py --output <path> getFormSchema "
-                "--formNumber <formNumber> and pass that file as --external-schema",
-                "PLUGIN_EXTERNAL_CONTRACT_UNVERIFIED",
-            )
         selectors = _contract_field_selectors(entry)
         resolved = [_external_field(scope, selector) for selector in selectors]
         entities = {row["entityKey"] for row, _key, _field in resolved}
@@ -648,16 +709,25 @@ def _verified_field(field_key: str, field: dict | None, entity: dict | None = No
         result.update({"entityKey": entity["entityKey"], "entityName": entity["entityName"]})
     if field.get("refEntity"):
         result["refEntity"] = field["refEntity"]
+    if field.get("comboOptions"):
+        result["comboOptions"] = field["comboOptions"]
     java_type = _field_java_type(field_type)
     if java_type:
         result["javaType"] = java_type
+    if field_type in ("TimeProp", "TimeField"):
+        result["valueAccessor"] = f'getInt("{field_key}")'
+        result["timeValueUnit"] = "seconds-after-midnight"
     return result
 
 
 def _verified_operation_keys(value: Any) -> set[str]:
     """Extract operation keys from a listOperations response without assuming one envelope."""
-    if isinstance(value, dict) and value.get("status") is False:
-        raise HandoffError("listOperations did not succeed")
+    if isinstance(value, dict):
+        data = value.get("data")
+        if (any(layer.get("status") is False or layer.get("success") is False
+                for layer in (value, data) if isinstance(layer, dict))
+                or value.get("errorCode") not in (None, "", 0, "0")):
+            raise HandoffError("listOperations did not succeed")
     found: set[str] = set()
 
     def visit(node: Any) -> None:
@@ -680,6 +750,195 @@ def _verified_operation_keys(value: Any) -> set[str]:
     return found
 
 
+def operation_contracts(value: Any, keys: list[str]) -> list[dict]:
+    """Preserve actual operation parameters instead of guessing business state transitions."""
+    if isinstance(value, list):
+        return [entry for child in value for entry in operation_contracts(child, keys)]
+    if not isinstance(value, dict):
+        return []
+    key = value.get("operationKey") or value.get("Key")
+    if key in keys:
+        return [{"operationKey": key, **{name: value[name] for name in
+            ("operationId", "operationName", "operationType", "parameter") if name in value}}]
+    return [entry for child in value.values() if isinstance(child, (dict, list))
+            for entry in operation_contracts(child, keys)]
+
+
+def read_platform(app_root: str, command: str, selector: str, flag: str = "--formNumber") -> Any:
+    import hashlib
+    destination = Path(app_root).resolve() / "_runtime" / "plugin-evidence" / (
+        command + "." + hashlib.sha256(selector.encode()).hexdigest()[:12] + "." + uuid.uuid4().hex + ".json")
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    # Do not let a previous successful file stand in for a failed current read.
+    destination.unlink(missing_ok=True)
+    try:
+        completed = subprocess.run([sys.executable, str(COSMIC_API), "--output", str(destination), command,
+            "--app-root", str(Path(app_root).resolve()), flag, selector],
+            capture_output=True, text=True, encoding="utf-8", errors="replace", timeout=60)
+    except (OSError, subprocess.TimeoutExpired) as exc:
+        raise HandoffError(f"{command} could not complete for {selector}", "PLUGIN_EVIDENCE_READ_FAILED") from exc
+    if completed.returncode or not destination.is_file():
+        raise HandoffError(f"{command} failed for {selector}; no fresh evidence saved",
+                           "PLUGIN_EVIDENCE_READ_FAILED")
+    value = _read_json(destination)
+    if isinstance(value, dict) and (value.get("status") is False
+            or value.get("errorCode") not in (None, "", 0, "0")
+            or isinstance(value.get("data"), dict) and value["data"].get("success") is False):
+        raise HandoffError(f"{command} failed for {selector}: {value.get('message') or value.get('errorCode')}",
+                           "PLUGIN_EVIDENCE_READ_FAILED")
+    return value
+
+
+def prepare_inputs(*, app_root: str, intent: dict, plugin_type: str, artifact_paths: list[str],
+                   run_result: Any, operation_result: Any, external_schemas: list[Any]) -> tuple[Any, list[Any]]:
+    """Collect only missing read-only platform evidence for this verified target."""
+    forms, entities, fields, _ = _catalog(artifact_paths, run_result)
+    main = _exact_one(forms, intent.get("form"), ("formName", "formNumber"), "form")
+    _string_list(intent.get("coreLogic"), "coreLogic", required=True)
+    _string_list(intent.get("scenes"), "scenes")
+    keys = _string_list(intent.get("operationKeys"), "operationKeys")
+    if plugin_type == "operation" and not keys:
+        raise HandoffError("type=operation requires operationKeys")
+    if plugin_type != "operation" and keys:
+        raise HandoffError("operationKeys are only valid for type=operation")
+    if isinstance(run_result, dict) and run_result.get("appRoot") and Path(run_result["appRoot"]).resolve() != Path(app_root).resolve():
+        raise HandoffError("write result belongs to another application", "PLUGIN_HANDOFF_UNRESOLVED")
+    specialized = intent.get("specialized") or {}
+    if not isinstance(specialized, dict) or "unresolvedDependencies" not in specialized:
+        raise HandoffError("declare specialized.unresolvedDependencies before platform reads")
+    if specialized.get("unresolvedDependencies"):
+        raise HandoffError("resolve declared dependencies before platform reads", "PLUGIN_EXTERNAL_CONTRACT_UNRESOLVED")
+    catalog = _external_entity_catalog(external_schemas)
+    if run_result is not None:
+        catalog += _artifact_external_catalog(entities, fields)
+    missing = [entry for name in ("externalContracts", "externalApis")
+        for entry in _contract_list(specialized.get(name), name)
+        if isinstance(entry, dict) and entry.get("entity")
+        and not _external_scope(catalog, str(entry["entity"]))]
+    selectors = list(dict.fromkeys(str(entry.get("formNumber") or entry["entity"]) for entry in missing))
+    invalid = [selector for selector in selectors if not re.fullmatch(r"[A-Za-z0-9_]+", selector)]
+    if invalid:
+        raise HandoffError("automatic schema reads require exact formNumber for: " + ", ".join(invalid),
+                           "PLUGIN_EXTERNAL_CONTRACT_UNVERIFIED")
+
+    from concurrent.futures import ThreadPoolExecutor
+    with ThreadPoolExecutor(max_workers=4) as pool:
+        schemas = list(pool.map(lambda selector: read_platform(app_root, "getFormSchema", selector), selectors))
+    if plugin_type == "operation" and operation_result is None:
+        operation_result = read_platform(app_root, "listOperations", main["formNumber"])
+    return operation_result, external_schemas + schemas
+
+
+def runtime_catalog(snapshots: list[Any]) -> tuple[list[dict], list[dict], list[dict], list[dict]]:
+    """Project getEntityType's native Properties/ItemType graph without authoring-key derivation."""
+    forms, entities, fields = [], [], []
+
+    def text(value: Any) -> str:
+        if isinstance(value, dict):
+            return str(value.get("zh_CN") or value.get("en_US") or "")
+        return str(value or "")
+
+    def visit(node: dict, form: dict, parent: dict | None = None, prop: dict | None = None) -> None:
+        key = str(node.get("Name") or "").strip()
+        properties = node.get("Properties")
+        if not key or not isinstance(properties, list):
+            raise HandoffError("runtime entity has no Name/Properties", "PLUGIN_CONTEXT_INCOMPLETE")
+        role = "header" if parent is None else "entries" if parent["role"] == "header" else "subentries"
+        collection = str((prop or {}).get("Name") or "")
+        path = parent["collectionPath"] + [collection] if parent else []
+        if parent and not collection:
+            raise HandoffError("runtime collection property has no Name", "PLUGIN_CONTEXT_INCOMPLETE")
+        entity = {**form, "entityKey": key, "entityName": text((prop or {}).get("DisplayName") or node.get("DisplayName")) or key,
+            "entityId": key, "authoringId": key, "entityType": node.get("_Type_"), "role": role,
+            "parentEntityKey": parent["entityKey"] if parent else None,
+            "collectionProperty": collection or None, "collectionPath": path}
+        entities.append(entity)
+        for property in properties:
+            if not isinstance(property, dict) or not property.get("Name"):
+                continue
+            kind = str(property.get("_Type_") or "")
+            if kind in {"EntryProp", "SubEntryProp"}:
+                item = property.get("ItemType")
+                if not isinstance(item, dict):
+                    raise HandoffError("runtime collection has no ItemType", "PLUGIN_CONTEXT_INCOMPLETE")
+                visit(item, form, entity, property)
+                continue
+            name = str(property["Name"])
+            if not kind:
+                raise HandoffError(f"runtime field {name} has no type", "PLUGIN_CONTEXT_INCOMPLETE")
+            fields.append({**entity, "fieldKey": name, "fieldName": text(property.get("DisplayName")) or name,
+                "fieldType": kind, "fieldId": property.get("Id"), "authoringId": name,
+                "fieldPath": ".".join(path + [name]), "refEntity": property.get("BaseEntityId") or "",
+                "required": property.get("MustInput") is True,
+                "refIdProperty": property.get("RefIdPropName"),
+                "metadataResourceId": (property.get("DisplayName") or {}).get("resId")
+                    if isinstance(property.get("DisplayName"), dict) else None,
+                "comboOptions": [{"label": text(option.get("Name")), "value": option.get("Value")}
+                    for option in property.get("ComboItems") or []]})
+
+    for snapshot in snapshots:
+        if not isinstance(snapshot, dict) or snapshot.get("status") is False:
+            raise HandoffError("runtime metadata read did not succeed", "PLUGIN_CONTEXT_INCOMPLETE")
+        data = snapshot.get("data", snapshot)
+        if isinstance(data, str):
+            data = json.loads(data)
+        if not isinstance(data, dict) or not data.get("Name"):
+            raise HandoffError("runtime metadata carries no entity definition", "PLUGIN_CONTEXT_INCOMPLETE")
+        form = {"formNumber": data["Name"], "formName": text(data.get("DisplayName")) or data["Name"],
+                "appCode": data.get("BizAppNumber"), "metadataVersion": data.get("Version"),
+                "metadataSource": "getEntityType"}
+        forms.append(form)
+        visit(data, form)
+        if not any(row["formNumber"] == form["formNumber"] for row in fields):
+            raise HandoffError("runtime entity carries no named fields", "PLUGIN_CONTEXT_INCOMPLETE")
+    return forms, entities, fields, []
+
+
+def prepare_runtime_inputs(app_root: str, form_number: str, intent: dict, plugin_type: str) -> tuple[list[Any], Any]:
+    """Read current main/explicitly referenced forms once, independently of modeling artifacts."""
+    _string_list(intent.get("coreLogic"), "coreLogic", required=True)
+    keys = _string_list(intent.get("operationKeys"), "operationKeys")
+    if plugin_type == "operation" and not keys:
+        raise HandoffError("type=operation requires operationKeys")
+    if plugin_type != "operation" and keys:
+        raise HandoffError("operationKeys are only valid for type=operation")
+    specialized = intent.get("specialized") or {}
+    if not isinstance(specialized, dict) or "unresolvedDependencies" not in specialized:
+        raise HandoffError("declare specialized.unresolvedDependencies before platform reads")
+    if specialized["unresolvedDependencies"]:
+        raise HandoffError("resolve declared dependencies before platform reads", "PLUGIN_EXTERNAL_CONTRACT_UNRESOLVED")
+    main = read_platform(app_root, "getEntityType", form_number, "--entityId")
+    forms, entities, fields, _ = runtime_catalog([main])
+    if forms[0]["formNumber"] != form_number:
+        raise HandoffError("runtime metadata belongs to another form", "PLUGIN_CONTEXT_INCOMPLETE")
+    archive = Path(app_root) / "archive.json"
+    identity = _read_json(archive) if archive.is_file() else {}
+    if forms[0].get("appCode") and identity.get("appCode") and forms[0]["appCode"] != identity["appCode"]:
+        raise HandoffError("runtime main form belongs to another application", "PLUGIN_CONTEXT_INCOMPLETE")
+    references = {field["refEntity"] for field in fields if field.get("refEntity")}
+    requests = []
+    catalog = _artifact_external_catalog(entities, fields)
+    for name in ("externalContracts", "externalApis"):
+        for entry in _contract_list(specialized.get(name), name):
+            if not isinstance(entry, dict) or not entry.get("entity") or _external_scope(catalog, str(entry["entity"])):
+                continue
+            selector = str(entry.get("formNumber") or entry["entity"])
+            if not re.fullmatch(r"[A-Za-z0-9_]+", selector):
+                # Resolve a unique declared reference's display name from its native metadata.
+                # Fetching declared reference targets is bounded to this form, never a global form tour.
+                requests += sorted(references)
+            else:
+                requests.append(selector)
+    from concurrent.futures import ThreadPoolExecutor
+    with ThreadPoolExecutor(max_workers=4) as pool:
+        related = list(pool.map(lambda selector: read_platform(app_root, "getEntityType", selector, "--entityId"),
+                               dict.fromkeys(requests)))
+    snapshots = [main] + related
+    runtime_catalog(snapshots)  # Fail before coding when any requested graph is incomplete.
+    operations = read_platform(app_root, "listOperations", form_number) if plugin_type == "operation" else None
+    return snapshots, operations
+
+
 def _bind_unique_mentions(
     records: list[dict], text: str, existing: dict[str, str],
     *, persisted_key: str, mention_keys: tuple[str, ...],
@@ -731,10 +990,16 @@ def prepare_handoff(
     *, app_root: str, project_root: str | None, plugin_type: str,
     intent: dict, artifact_paths: list[str], run_result: Any = None,
     operation_result: Any = None, external_schemas: list[Any] | None = None,
+    runtime_metadata: list[Any] | None = None,
 ) -> dict:
     if not isinstance(intent, dict):
         raise HandoffError("intent must be a JSON object")
-    forms, entities, fields, registered_plugins = _catalog(artifact_paths, run_result)
+    if runtime_metadata is not None:
+        if not runtime_metadata:
+            raise HandoffError("runtime metadata is empty", "PLUGIN_CONTEXT_INCOMPLETE")
+        artifact_paths = []
+    forms, entities, fields, registered_plugins = (runtime_catalog(runtime_metadata) if runtime_metadata
+        else _catalog(artifact_paths, run_result))
     main_form = _exact_one(forms, intent.get("form"), ("formName", "formNumber"), "form")
     related = None
     if intent.get("relatedForm"):
@@ -748,6 +1013,12 @@ def prepare_handoff(
         if operation_result is None:
             raise HandoffError("type=operation requires a listOperations read-back via --operations-file")
         verified_operations = _verified_operation_keys(operation_result)
+        operation_data = operation_result.get("data") if isinstance(operation_result, dict) else None
+        if isinstance(operation_data, dict):
+            if operation_data.get("formNumber") and operation_data["formNumber"] != main_form["formNumber"]:
+                raise HandoffError("listOperations result belongs to another form")
+            if operation_data.get("appRoot") and Path(operation_data["appRoot"]).resolve() != Path(app_root).resolve():
+                raise HandoffError("listOperations result belongs to another application")
         missing_operations = [key for key in operation_keys if key not in verified_operations]
         if missing_operations:
             raise HandoffError(
@@ -851,7 +1122,15 @@ def prepare_handoff(
                 "PLUGIN_SOURCE_NOT_FOUND",
             )
         class_name = class_name or existing.stem
-        existing_methods = method_signatures(existing.read_text(encoding="utf-8-sig"))
+        source_text = existing.read_text(encoding="utf-8-sig")
+        existing_methods = method_signatures(source_text)
+        declared_package = re.search(r"\bpackage\s+([A-Za-z_][\w.]*)\s*;", stripped(source_text))
+        if declared_package:
+            source_package = declared_package.group(1).replace(".", "/")
+            if form_plugins and source_package != package_path:
+                raise HandoffError("existing source package conflicts with the registered plugin class", "PLUGIN_CLASS_NOT_REGISTERED")
+            package_path = source_package
+            package_source = "existing source declaration"
     else:
         # An existing file at the create-new target means the class is already in this project,
         # so generating it again would either duplicate its methods or overwrite its logic. The
@@ -870,6 +1149,8 @@ def prepare_handoff(
                 f'ownershipMode=modify with sourcePath "{target}"',
                 "PLUGIN_OWNERSHIP_CONFLICT",
             )
+        class_name = candidate or class_name
+        source_path = str(target) if target else source_path
 
     entity_selectors = intent.get("entities") or {}
     field_selectors = intent.get("fields") or {}
@@ -900,6 +1181,11 @@ def prepare_handoff(
             "PLUGIN_EXTERNAL_CONTRACT_UNRESOLVED",
         )
     external_catalog = _external_entity_catalog(external_schemas or [])
+    if run_result is not None or runtime_metadata:
+        external_catalog += [
+            row for row in _artifact_external_catalog(entities, fields)
+            if not any(existing["entityKey"] == row["entityKey"] for existing in external_catalog)
+        ]
     for key in ("externalContracts", "externalApis"):
         specialized[key] = _verify_external_contracts(specialized[key], external_catalog)
     entity_map = {
@@ -911,14 +1197,14 @@ def prepare_handoff(
         for label, selector in field_selectors.items()
     }
     logic_text = "\n".join(core_logic)
-    auto_entities = _bind_unique_mentions(
+    auto_entities = ([] if runtime_metadata else _bind_unique_mentions(
         entities, logic_text, entity_map,
         persisted_key="entityKey", mention_keys=("entityKey", "entityName", "authoringId"),
-    )
-    auto_fields = _bind_unique_mentions(
+    ))
+    auto_fields = ([] if runtime_metadata else _bind_unique_mentions(
         fields, logic_text, field_map,
         persisted_key="fieldKey", mention_keys=("fieldKey", "fieldName", "authoringId"),
-    )
+    ))
     # Built after auto-binding so a field the core logic mentioned by name carries the same type
     # evidence as one the intent selected explicitly.
     contracts_by_key: dict[str, dict | None] = {}
@@ -931,11 +1217,9 @@ def prepare_handoff(
             contracts_by_key[key] = None
             continue
         contracts_by_key[key] = contract
-    field_contracts = [
-        contracts_by_key[key]
-        for key in dict.fromkeys(field_map.values())
-        if contracts_by_key.get(key)
-    ]
+    field_contracts = ([_field_contract(row) for row in fields if row["fieldKey"] in field_map.values()] if runtime_metadata else [
+        contracts_by_key[key] for key in dict.fromkeys(field_map.values()) if contracts_by_key.get(key)
+    ])
     handoff = {
         "appRoot": str(Path(app_root).resolve()),
         "projectRoot": path_result["projectRoot"],
@@ -950,7 +1234,54 @@ def prepare_handoff(
         "fields": field_map,
         "coreLogic": core_logic,
         "specialized": specialized,
+        "description": (str(intent.get("description") or "").strip() or core_logic[0])[:20],
     }
+    if runtime_metadata:
+        def graph(form: dict) -> dict:
+            return {key: form[key] for key in ("formNumber", "formName", "metadataSource", "metadataVersion")} | {
+                "entities": [{key: entity[key] for key in
+                    ("entityKey", "entityName", "entityType", "role", "parentEntityKey", "collectionProperty", "collectionPath")}
+                    | {"fields": [_field_contract(row) for row in fields
+                       if row["formNumber"] == form["formNumber"] and row["entityKey"] == entity["entityKey"]]}
+                    for entity in entities if entity["formNumber"] == form["formNumber"]]}
+        handoff["formGraph"] = graph(main_form)
+        handoff["relatedForms"] = [graph(form) for form in forms if form["formNumber"] != main_form["formNumber"]]
+        handoff["entities"].update({row["entityName"]: row["entityKey"] for row in entities
+                                   if row["formNumber"] == main_form["formNumber"]})
+    if operation_keys:
+        handoff["operationContracts"] = operation_contracts(operation_result, operation_keys)
+        if runtime_metadata:
+            handoff["availableOperations"] = [{key: operation[key] for key in
+                ("operationKey", "operationName", "operationType") if key in operation}
+                for operation in operation_contracts(operation_result, sorted(verified_operations))]
+        handoff["stateFields"] = [{key: row[key] for key in
+            ("fieldKey", "fieldName", "fieldId", "entityKey", "comboOptions")}
+            for row in fields if row.get("comboOptions")]
+        warnings = []
+        for operation in handoff["operationContracts"]:
+            parameter = operation.get("parameter")
+            if not isinstance(parameter, dict):
+                continue
+            target_id = parameter.get("StatusFieldId")
+            if not target_id or "Value" not in parameter:
+                continue
+            targets = [row for row in fields if row["formNumber"] == main_form["formNumber"] and
+                (row.get("fieldId") == target_id or str(row.get("metadataResourceId") or "").endswith("." + str(target_id) + ".Name"))]
+            target = targets[0] if len(targets) == 1 else None
+            if target:
+                operation["statusFieldKey"] = target["fieldKey"]
+            if target is None:
+                warnings.append({"operationKey": operation["operationKey"], "statusFieldId": target_id,
+                    "value": parameter["Value"], "code": "OPERATION_STATE_TARGET_UNRESOLVED",
+                    "message": "Do not equate this operation with a business state until its status field is resolved."})
+                continue
+            options = target.get("comboOptions") or []
+            if options and not any(str(option.get("value")) == str(parameter["Value"]) for option in options):
+                warnings.append({"operationKey": operation["operationKey"], "fieldKey": target["fieldKey"],
+                    "value": parameter["Value"], "code": "OPERATION_STATE_VALUE_MISMATCH",
+                    "message": "Operation value is absent from the verified field options; resolve the business mapping before coding."})
+        if warnings:
+            handoff["stateWarnings"] = warnings
     if field_contracts:
         # `fields` stays a bare {label: fieldKey} map because it is what the coding step turns
         # into constants. The value types travel alongside it so a reference field cannot be
@@ -973,6 +1304,12 @@ def prepare_handoff(
         handoff["className"] = class_name
     if source_path:
         handoff["sourcePath"] = str(Path(source_path).expanduser().resolve())
+    if class_name:
+        handoff["fqcn"] = package_path.replace("/", ".") + "." + class_name
+    try:
+        handoff["codingEvidence"] = plugin_coding_evidence(plugin_type, _string_list(intent.get("scenes"), "scenes"))
+    except ValueError as exc:
+        raise HandoffError(str(exc), "PLUGIN_CODING_EVIDENCE_INVALID") from exc
     if ownership_mode == "modify":
         # The methods the target class already declares, always present for modify so an empty
         # list means an empty class body rather than an unread file. New logic belongs inside
@@ -998,18 +1335,86 @@ def prepare_handoff(
     }
 
 
+def handoff_response(result: dict, *, full_output: bool = False) -> dict:
+    """Keep the CLI below the host output limit; the saved context remains complete."""
+    if full_output:
+        return {key: result[key] for key in ("status", "handoffPath", "handoff")}
+    handoff = result["handoff"]
+    coding = handoff.get("codingEvidence", {})
+    graphs = [handoff["formGraph"], *handoff.get("relatedForms", [])] if handoff.get("formGraph") else []
+    return {
+        "status": result["status"],
+        "handoffPath": result["handoffPath"],
+        "contextMode": "reference-only",
+        "handoff": {
+            **{key: handoff[key] for key in (
+                "appRoot", "projectRoot", "packagePath", "type", "ownershipMode", "formNumber",
+                "className", "sourcePath", "fqcn", "operationKeys", "sourceGate",
+            ) if key in handoff},
+            **({'targetSdk': {key: handoff['targetSdk'][key] for key in
+                ('status', 'projectRoot', 'module', 'evidenceScope') if key in handoff['targetSdk']}}
+               if 'targetSdk' in handoff else {}),
+            "codingEvidence": {
+                **{key: coding[key] for key in ("codingEntry", "guide", "typeKnowledge", "apiLookup", "sdkLookup", "operationDispatch") if key in coding},
+                "signatureTypes": coding.get("signatureTypes", [])[:12],
+                "signatureTypeCount": len(coding.get("signatureTypes", [])),
+            },
+        },
+        "metadata": {
+            "formCount": len(graphs),
+            "forms": [{
+                **{key: graph[key] for key in ("formNumber", "metadataSource", "metadataVersion") if key in graph},
+                "entityCount": len(graph.get("entities", [])),
+                "fieldCount": sum(len(entity.get("fields", [])) for entity in graph.get("entities", [])),
+            } for graph in graphs[:8]],
+        },
+        "contextSections": ["handoff.formGraph", "handoff.relatedForms", "handoff.specialized",
+                            "handoff.operationContracts", "handoff.stateFields", "handoff.stateWarnings",
+                            "handoff.codingEvidence", "handoff.reportContract", "handoff.targetSdk"],
+        "instruction": (
+            "This response is a summary, not the coding context. Keep the complete saved handoffPath "
+            "for native compilation; begin with query_plugin_handoff.py coding-start, then query only missing field paths, collection hierarchy, external contracts, "
+            "operation values, warnings and SDK signatures needed for this class with query_plugin_handoff.py. "
+            "Index or find exact paths before get; do not read the whole JSON into the model. Use its exact codingEntry "
+            "and verified signatureTypes imports; missing or ambiguous SDK types require the supplied API lookup. "
+            "Pass handoffPath directly to compile_plugin_source.py --handoff; do not search for another file."
+        ),
+    }
+
+
+def assert_handoff_replace(destination: Path, result: dict, replace: bool = False) -> None:
+    if not destination.is_file() or replace:
+        return
+    existing = _read_json(destination)
+    previous = existing.get("handoff") if isinstance(existing, dict) and existing.get("status") is True else None
+    current = result["handoff"]
+    fields = ("projectRoot", "appRoot", "sourcePath", "fqcn", "formNumber", "type", "coreLogic")
+    if not isinstance(previous, dict) or any(previous.get(key) != current.get(key) for key in fields) or sorted(
+            previous.get("operationKeys", [])) != sorted(current.get("operationKeys", [])):
+        raise HandoffError(
+            f"Prepared class already has a different snapshot at {destination}. "
+            "Review the existing snapshot and reconcile the class identity and business scope before explicitly replacing it with --replace-handoff.",
+            "PLUGIN_HANDOFF_CONFLICT")
+
+
 def main() -> None:
     parser = argparse.ArgumentParser(description="Prepare a verified compact Java-plugin handoff")
     parser.add_argument("--app-root", required=True)
     parser.add_argument("--java-project-root", "--project-root", dest="project_root")
     parser.add_argument("--type", required=True, dest="plugin_type")
-    parser.add_argument("--artifact", action="append", required=True, dest="artifact_paths")
+    parser.add_argument("--replace-handoff", action="store_true")
+    artifacts = parser.add_mutually_exclusive_group()
+    artifacts.add_argument("--artifact", action="append", dest="artifact_paths")
+    artifacts.add_argument("--emit-manifest", help="Exact manifest path returned by the emitter; includes every declared artifact")
     parser.add_argument("--run-result")
-    parser.add_argument("--operations-file", help="JSON stdout from listOperations; required for type=operation")
+    parser.add_argument("--form-number", help="Exact existing form number; independently reads runtime metadata")
+    parser.add_argument("--operations-file", help="Reuse an existing listOperations result; otherwise read once automatically")
+    parser.add_argument("--output", help="Save prepared context here; default is the app-local class handoff file")
+    parser.add_argument("--full-output", action="store_true", help="Print the complete handoff JSON instead of its compact summary")
+    parser.add_argument("--prepare-source", action="store_true", help="Mark this verified class writable for implementation; does not write Java source")
     parser.add_argument(
         "--external-schema", action="append", dest="external_schemas",
-        help="JSON stdout from getFormSchema for an entity outside the artifacts; required for "
-             "every specialized.externalContracts entry that names an entity. Repeatable.",
+        help="JSON from getFormSchema for an entity contract outside the verified artifact batch. Repeatable.",
     )
     intent_group = parser.add_mutually_exclusive_group(required=True)
     intent_group.add_argument("--intent-json")
@@ -1017,21 +1422,62 @@ def main() -> None:
     args = parser.parse_args()
     try:
         intent = json.loads(args.intent_json) if args.intent_json else _read_json(args.intent_file)
+        if not isinstance(intent, dict):
+            raise HandoffError("intent must be a JSON object")
         run_result = _read_json(args.run_result) if args.run_result else None
+        if run_result is not None and not isinstance(run_result, dict):
+            raise HandoffError("write result must be a JSON object")
         operation_result = _read_json(args.operations_file) if args.operations_file else None
+        artifact_paths = (manifest_artifacts(args.emit_manifest) if args.emit_manifest else args.artifact_paths
+                          or (run_result or {}).get("artifactPaths"))
+        runtime_metadata = None
+        if args.form_number or not artifact_paths or args.plugin_type == "operation":
+            form_number = args.form_number or str(intent.get("form") or "")
+            if not args.form_number and artifact_paths:
+                hints = (run_result or {}).get("forms") or _catalog(artifact_paths, run_result)[0]
+                form_number = _exact_one(hints, intent.get("form"), ("formName", "formNumber"), "form")["formNumber"]
+            if not re.fullmatch(r"[A-Za-z0-9_]+", form_number):
+                raise HandoffError("independent preparation requires --form-number with an exact existing form code")
+            runtime_metadata, operation_result = prepare_runtime_inputs(args.app_root, form_number, intent, args.plugin_type)
+            intent["form"] = form_number
+            artifact_paths = []
+        else:
+            operation_result, external_schemas = prepare_inputs(
+                app_root=args.app_root, intent=intent, plugin_type=args.plugin_type,
+                artifact_paths=artifact_paths, run_result=run_result, operation_result=operation_result,
+                external_schemas=[_read_json(path) for path in args.external_schemas or []])
         result = prepare_handoff(
-            app_root=args.app_root,
-            project_root=args.project_root,
-            plugin_type=args.plugin_type,
-            intent=intent,
-            artifact_paths=args.artifact_paths,
-            run_result=run_result,
-            operation_result=operation_result,
-            external_schemas=[_read_json(path) for path in args.external_schemas or []],
+            app_root=args.app_root, project_root=args.project_root, plugin_type=args.plugin_type,
+            intent=intent, artifact_paths=artifact_paths, run_result=run_result,
+            operation_result=operation_result, runtime_metadata=runtime_metadata,
+            external_schemas=([_read_json(path) for path in args.external_schemas or []]
+                              if runtime_metadata else external_schemas),
         )
-        print(json.dumps(result, ensure_ascii=False))
-    except (HandoffError, json.JSONDecodeError) as exc:
-        error_code = getattr(exc, "error_code", "PLUGIN_HANDOFF_UNRESOLVED")
+        destination = (Path(args.output).resolve() if args.output else Path(args.app_root).resolve()
+                       / "_runtime" / "plugin-handoffs" / (result["handoff"]["className"] + ".json"))
+        assert_handoff_replace(destination, result, args.replace_handoff)
+        if args.prepare_source:
+            from plugin_target_sdk import verify_target_sdk
+            result['handoff']['targetSdk'] = verify_target_sdk(result['handoff']['projectRoot'],
+                result['handoff']['codingEvidence'], intent.get('sdkUsage'))
+            from plugin_source_gate import write_state, gate_path
+            import os
+            handoff = result["handoff"]
+            if not handoff.get("className") or not handoff.get("sourcePath"):
+                raise HandoffError("source preparation requires a resolved className and sourcePath")
+            target = Path(handoff["sourcePath"]).resolve()
+            if not target.is_relative_to(Path(handoff["projectRoot"]).resolve() / "src" / "main" / "java"):
+                raise HandoffError("source preparation target is outside the verified Java module", "PLUGIN_SOURCE_INVALID")
+            target.parent.mkdir(parents=True, exist_ok=True)
+            write_state(handoff["projectRoot"], handoff["className"], "coding",
+                        os.environ.get("LINGEE_SESSION_ID") or os.environ.get("OPENCODE_SESSION_ID"), emit=False)
+            handoff["sourceGate"] = {"state": "coding", "path": gate_path(handoff["projectRoot"], handoff["className"])}
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        result["handoffPath"] = str(destination)
+        destination.write_text(json.dumps(result, ensure_ascii=False, indent=2), encoding="utf-8")
+        print(json.dumps(handoff_response(result, full_output=args.full_output), ensure_ascii=False))
+    except (HandoffError, json.JSONDecodeError, ValueError) as exc:
+        error_code = getattr(exc, "error_code", getattr(exc, "code", "PLUGIN_HANDOFF_UNRESOLVED"))
         print(json.dumps({"status": False, "errorCode": error_code, "message": str(exc)}, ensure_ascii=False))
         raise SystemExit(2)