@shundoo-ai/dsh-cosmic 1.0.21 → 1.0.22

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

@@ -622,6 +622,20 @@ def test_report_handoff_carries_the_compiled_presentation_contract(tmp_path):
     assert bound[0]["requiredBy"] == ["amount"]
 
 
+def test_report_handoff_preserves_default_sorts_and_interactive_priority(tmp_path):
+    artifact = _report_artifact()
+    artifact["reportColumns"][1]["dateIndex"] = "TotalAmount"
+    artifact["reportSorts"] = [{"fieldKey": "amount", "direction": "desc"},
+                               {"fieldKey": "org_name", "direction": "asc"}]
+    contract = _report_handoff(tmp_path, artifact)["reportContract"]
+    assert contract["defaultSorts"] == [
+        {"fieldKey": "amount", "dateIndex": "TotalAmount", "direction": "desc"},
+        {"fieldKey": "org_name", "dateIndex": "org_name", "direction": "asc"},
+    ]
+    assert contract["defaultSortPolicy"]["priority"] == "interactiveThenDefault"
+    assert contract["defaultSortPolicy"]["runtimeVerified"] is False
+
+
 def test_report_handoff_carries_filter_requirements_the_platform_dropped(tmp_path):
     payload = _report_handoff(tmp_path, _report_artifact(must_input=True))
 
@@ -691,6 +705,79 @@ def test_report_handoff_binds_a_column_whose_key_differs_from_its_dataset_column
     assert binding["javaFollowUp"] == ['setDateIndex("material_id")']
 
 
+def test_report_handoff_prepares_the_left_tree_plugin_from_its_own_slot(tmp_path):
+    """The left tree's class is registered as reportProperties.tree.ReportPlugin, not reportPlugins.
+
+    Reading only reportPlugins made it unpreparable: the list plugin was registered, so naming the
+    tree class failed with PLUGIN_CLASS_NOT_REGISTERED, and its registered package was never the
+    one the source landed in.
+    """
+    artifact = _report_artifact()
+    artifact["reportProperties"] = {"tree": {"ReportPlugin": "kd.uhyl.report.tree.KpiTreePlugin"}}
+    app_root = tmp_path / "app" / "uhyl_demo"
+    _write(app_root / "archive.json", {"appCode": "uhyl_demo"})
+    _java_project(tmp_path)
+    artifact_path = tmp_path / "kpi_rpt.artifact.json"
+    _write(artifact_path, artifact)
+    intent = {
+        "form": "KPI 报表", "trigger": "报表左树加载时", "className": "KpiTreePlugin",
+        "coreLogic": ["按组织构建左树"],
+        "specialized": {"externalContracts": [], "unresolvedDependencies": []},
+    }
+    payload = prepare_handoff(
+        app_root=str(app_root), project_root=str(tmp_path), plugin_type="reporttreelist",
+        intent=intent, artifact_paths=[str(artifact_path)],
+        run_result=_report_run_result(artifact_path.name),
+    )["handoff"]
+
+    assert payload["packagePath"] == "kd/uhyl/report/tree"
+    assert payload["reportContract"]["pluginTypes"] == {
+        "kd.uhyl.report.KpiReportPlugin": "reportlist",
+        "kd.uhyl.report.tree.KpiTreePlugin": "reporttreelist",
+    }
+
+
+def _report_slot_handoff(tmp_path, artifact, plugin_type, intent):
+    app_root = tmp_path / "app" / "uhyl_demo"
+    _write(app_root / "archive.json", {"appCode": "uhyl_demo"})
+    _java_project(tmp_path)
+    artifact_path = tmp_path / "kpi_rpt.artifact.json"
+    _write(artifact_path, artifact)
+    return prepare_handoff(
+        app_root=str(app_root), project_root=str(tmp_path), plugin_type=plugin_type,
+        intent={"form": "KPI 报表", "coreLogic": ["按组织汇总金额"],
+                "specialized": {"externalContracts": [], "unresolvedDependencies": []}, **intent},
+        artifact_paths=[str(artifact_path)], run_result=_report_run_result(artifact_path.name),
+    )["handoff"]
+
+
+def test_report_handoff_prepares_the_report_form_plugin_beside_its_data_plugin(tmp_path):
+    """A reportform plugin is the report form's own plugin and sits in neither registered slot.
+
+    Matching it against the slot classes refused its className with PLUGIN_CLASS_NOT_REGISTERED,
+    and with no className the coding step was handed the data plugin's class and package.
+    """
+    payload = _report_slot_handoff(tmp_path, _report_artifact(), "reportform", {
+        "trigger": "点击超链接时", "className": "KpiDrillReportPlugin"})
+
+    assert payload["className"] == "KpiDrillReportPlugin"
+    assert payload["packagePathSource"] == "appCode convention"
+    # The form plugin still receives the column contract: it reads each row by column name.
+    assert "org_name" in payload["reportContract"]["dataSetColumns"]
+
+
+def test_report_handoff_finds_the_data_plugin_by_its_own_slot(tmp_path):
+    """With a left tree registered as well, the data-fetch handoff needs no className."""
+    artifact = _report_artifact()
+    artifact["reportProperties"] = {"tree": {"ReportPlugin": "kd.uhyl.report.tree.KpiTreePlugin"}}
+
+    payload = _report_slot_handoff(tmp_path, artifact, "reportlist", {"trigger": "报表查询时"})
+
+    assert payload["className"] == "KpiReportPlugin"
+    assert payload["packagePath"] == "kd/uhyl/report"
+    assert payload["packagePathSource"] == "registered plugin className"
+
+
 def _bos_user_schema():
     """A getFormSchema read-back for an entity no artifact describes."""
     return {"errorCode": "0", "data": {"formNumber": "bos_user", "entities": [{
@@ -1187,7 +1274,7 @@ def test_recorded_runtime_graph_resolves_header_entries_and_subentries_without_a
     native = json.loads((Path(__file__).parent / "fixtures/java_context_booking_native.json").read_text())
     _java_project(tmp_path)
     app = tmp_path / "app" / "sample_app"
-    _write(app / "archive.json", {"appCode": "sample_app"})
+    _write(app / "archive.json", {"appCode": "sample_app", "appId": "SAMPLE-ID"})
     intent = {"form": "定场单", "trigger": "保存时", "operationKeys": ["save"], "coreLogic": ["校验场地时段冲突"],
         "fields": {"date": {"form": "定场单", "entity": "header", "field": "定场日期"},
                    "price": {"form": "定场单", "entity": "entries", "field": "单价"},
@@ -1222,7 +1309,7 @@ def test_runtime_context_without_field_declarations_still_has_the_complete_graph
     native = json.loads((Path(__file__).parent / "fixtures/java_context_booking_native.json").read_text())
     _java_project(tmp_path)
     app = tmp_path / "app" / "sample_app"
-    _write(app / "archive.json", {"appCode": "sample_app"})
+    _write(app / "archive.json", {"appCode": "sample_app", "appId": "SAMPLE-ID"})
     result = prepare_handoff(app_root=str(app), project_root=str(tmp_path), plugin_type="operation",
         intent={"form": "定场单", "trigger": "保存时", "operationKeys": ["save"], "coreLogic": ["校验场地状态"],
                 "specialized": {"unresolvedDependencies": []}}, artifact_paths=[], runtime_metadata=[native],
@@ -1285,7 +1372,7 @@ def test_independent_cli_reads_native_metadata_without_modeling_receipts(tmp_pat
     _write(config, {"compile": False})
     monkeypatch.setenv("KD_APPCONFIG", str(config))
     app = tmp_path / "app" / "sample_app"
-    _write(app / "archive.json", {"appCode": "sample_app"})
+    _write(app / "archive.json", {"appCode": "sample_app", "appId": "SAMPLE-ID"})
     responses = tmp_path / "responses.json"
     _write(responses, {"getEntityType": {"sample_booking_order": native,
         "sample_court": {"status": True, "data": {"Name": "sample_court", "DisplayName": {"zh_CN": "场地档案"},
@@ -1329,6 +1416,11 @@ def test_independent_cli_reads_native_metadata_without_modeling_receipts(tmp_pat
         assert result["handoff"] == saved["handoff"]
     else:
         assert result["contextMode"] == "reference-only"
+        assert result["codingStartCommand"][-3:] == ["coding-start", "--handoff", result["handoffPath"]]
+        import subprocess
+        started = subprocess.run(result["codingStartCommand"], capture_output=True, text=True)
+        assert started.returncode == 0, started.stdout + started.stderr
+        assert json.loads(started.stdout)["handoffPath"] == result["handoffPath"]
         assert "formGraph" not in result["handoff"]
         assert result["metadata"]["forms"][0]["metadataSource"] == "getEntityType"
     recorded = [json.loads(line) for line in calls.read_text().splitlines()]
@@ -1349,7 +1441,7 @@ def test_large_native_coding_context_is_saved_completely_without_truncating_stdo
     ]
     _java_project(tmp_path)
     app = tmp_path / "app" / "sample_app"
-    _write(app / "archive.json", {"appCode": "sample_app"})
+    _write(app / "archive.json", {"appCode": "sample_app", "appId": "SAMPLE-ID"})
     handoff = prepare_handoff(
         app_root=str(app), project_root=str(tmp_path), plugin_type="operation", artifact_paths=[],
         runtime_metadata=[native], operation_result={"status": True, "data": [{"operationKey": "save"}]},
@@ -1381,3 +1473,858 @@ def test_prepared_class_assignment_cannot_be_silently_overwritten(tmp_path):
     assert error.value.error_code == "PLUGIN_HANDOFF_CONFLICT"
     assert target.read_bytes() == original
     assert_handoff_replace(target, revised, replace=True)
+
+
+@pytest.mark.parametrize('key,value', [('reportContract', {'dataSetColumns': ['person_id']}),
+    ('sdkUsage', [{'class': 'kd.bos.entity.report.ReportColumn'}]),
+    ('specialized', {'externalContracts': [{'entity': 'bos_user'}]})])
+def test_handoff_replace_protects_contract_and_sdk_changes(tmp_path, key, value):
+    from prepare_plugin_handoff import assert_handoff_replace
+    destination = tmp_path / 'handoff.json'
+    result = {'status': True, 'handoff': {'fqcn': 'sample.Plugin', 'coreLogic': ['query']}}
+    _write(destination, result)
+    with pytest.raises(HandoffError) as error:
+        assert_handoff_replace(destination, {'status': True, 'handoff': {**result['handoff'], key: value}})
+    assert error.value.error_code == 'PLUGIN_HANDOFF_CONFLICT'
+    assert json.loads(destination.read_text()) == result
+
+
+@pytest.mark.parametrize('compile,prepare,expected', [(False, True, '0'),
+    (False, False, 'PLUGIN_WORKSPACE_UNRESOLVED'), (True, True, 'PLUGIN_WORKSPACE_UNRESOLVED')])
+def test_explicit_source_only_workspace_is_prepared_only_when_requested(tmp_path, monkeypatch, compile, prepare, expected):
+    config = tmp_path / 'appconfig.json'
+    _write(config, {'compile': compile})
+    monkeypatch.setenv('KD_APPCONFIG', str(config))
+    app = tmp_path / 'app' / 'sample_demo'
+    _write(app / 'archive.json', {'appCode': 'sample_demo'})
+    source = tmp_path / 'explicit-sources'
+    result = resolve_output_path(str(app), 'reportlist', str(source), prepare_source=prepare)
+    assert result['errorCode'] == expected
+    assert (source / 'src' / 'main' / 'java').exists() == (expected == '0')
+    assert not (source / 'build.gradle').exists()
+    unsupported = tmp_path / 'unsupported'
+    assert resolve_output_path(str(app), 'unknown', str(unsupported), prepare_source=True)['errorCode'] == 'PLUGIN_TYPE_UNSUPPORTED'
+    assert not unsupported.exists()
+
+
+def test_report_incremental_state_rejects_old_artifact_and_reuses_current_filter_evidence(tmp_path):
+    from _core.report_ops import write_report_authoring_state, sync_report_authoring_state
+    app = tmp_path / 'app' / 'uhyl_demo'
+    _write(app / 'archive.json', {'appCode': 'uhyl_demo'})
+    _java_project(tmp_path)
+    artifact = _report_artifact(must_input=True)
+    before = {'readBackAvailable': True, 'readBackSource': 'canonical',
+              'reportColumns': artifact['reportColumns'], 'reportFilters': artifact['reportFilters']}
+    write_report_authoring_state(str(app), 'uhyl_kpi_rpt', 'FORM', artifact, before)
+    after = {**before, 'reportFilters': []}
+    saved = sync_report_authoring_state(str(app), 'uhyl_kpi_rpt', 'FORM', 'filters', [], before, after, {'verified': True})
+    path = tmp_path / 'old-artifact.json'
+    _write(path, artifact)
+    intent = {'form': 'KPI 报表', 'trigger': '报表查询', 'coreLogic': ['汇总金额'],
+              'specialized': {'unresolvedDependencies': []}}
+    with pytest.raises(HandoffError) as error:
+        prepare_handoff(app_root=str(app), project_root=str(tmp_path), plugin_type='reportlist',
+            artifact_paths=[str(path)], run_result=_report_run_result(path.name), intent=intent)
+    assert error.value.error_code == 'PLUGIN_REPORT_STATE_STALE'
+    result = prepare_handoff(app_root=str(app), project_root=str(tmp_path), plugin_type='reportlist',
+        artifact_paths=[saved['artifactPath']], run_result=_report_run_result(Path(saved['artifactPath']).name), intent=intent)
+    assert result['handoff']['reportContract']['filterEnforcement'] == []
+    assert result['handoff']['reportContract']['filterValueContracts'] == []
+    assert result['reportStatePath'] == saved['path']
+
+
+def test_report_reconciliation_reads_current_metadata_and_never_writes_platform(tmp_path, monkeypatch):
+    import prepare_plugin_handoff as module
+    from _core.report_ops import report_authoring_path, _build_filters_payload
+    artifact = _report_artifact()
+    app = tmp_path / 'app' / 'uhyl_demo'
+    _write(app / 'archive.json', {'appCode': 'uhyl_demo'})
+    _java_project(tmp_path)
+    path = tmp_path / 'artifact.json'
+    _write(path, artifact)
+    _write(report_authoring_path(str(app), 'uhyl_kpi_rpt'), {'status': 'incomplete'})
+    calls = []
+    def read(root, cmd, selector):
+        calls.append((cmd, selector))
+        return {'readBackAvailable': True, 'readBackSource': 'canonical', 'formNumber': 'uhyl_kpi_rpt',
+                'formId': 'FORM', 'reportColumns': artifact['reportColumns'], 'reportFilters': _build_filters_payload(artifact['reportFilters'])}
+    monkeypatch.setattr(module, 'read_platform', read)
+    result = prepare_handoff(app_root=str(app), project_root=str(tmp_path), plugin_type='reportlist',
+        artifact_paths=[str(path)], run_result=_report_run_result(path.name), refresh_report_state=True,
+        intent={'form': 'KPI 报表', 'trigger': '报表查询', 'coreLogic': ['汇总金额'], 'specialized': {'unresolvedDependencies': []}})
+    assert calls == [('getReportSchema', 'uhyl_kpi_rpt')]
+    assert result['handoff']['reportContract']['dataSetColumns'] == ['org_name', 'amount', 'currency_id']
+    assert result['inputFiles'][0]['path'] == str(report_authoring_path(str(app), 'uhyl_kpi_rpt'))
+    with pytest.raises(HandoffError) as error:
+        prepare_handoff(app_root=str(app), project_root=str(tmp_path), plugin_type='reportlist',
+            artifact_paths=[str(path)], run_result={**_report_run_result(path.name), 'formId': 'OTHER'},
+            intent={'form': 'KPI 报表', 'trigger': '报表查询', 'coreLogic': ['汇总金额'], 'specialized': {'unresolvedDependencies': []}})
+    assert error.value.error_code == 'PLUGIN_REPORT_STATE_STALE'
+
+
+@pytest.mark.parametrize('mode', ['changed-input', 'save-failed', 'gate-failed', 'success'])
+def test_prepare_does_not_advance_gate_when_inputs_change_or_snapshot_cannot_be_saved(tmp_path, monkeypatch, capsys, mode):
+    import os
+    import prepare_plugin_handoff as module
+    import plugin_source_gate
+    app = tmp_path / 'app' / 'uhyl_demo'
+    _write(app / 'archive.json', {'appCode': 'uhyl_demo'})
+    _java_project(tmp_path)
+    config = tmp_path / 'appconfig.json'
+    _write(config, {'compile': False})
+    monkeypatch.setenv('KD_APPCONFIG', str(config))
+    artifact = tmp_path / 'artifact.json'
+    _write(artifact, _report_artifact())
+    intent = tmp_path / 'intent.json'
+    _write(intent, {'form': 'KPI 报表', 'trigger': '报表查询', 'coreLogic': ['汇总金额'], 'specialized': {'unresolvedDependencies': []}})
+    original = module.prepare_handoff
+    def prepare(**kwargs):
+        result = original(**kwargs)
+        if mode == 'changed-input':
+            _write(intent, {'form': 'KPI 报表', 'trigger': '报表查询', 'coreLogic': ['新需求']})
+        return result
+    monkeypatch.setattr(module, 'prepare_handoff', prepare)
+    monkeypatch.setattr(module, 'prepare_inputs', lambda **kwargs: (None, []))
+    calls = []
+    def gate(*args, **kwargs):
+        calls.append(args)
+        if mode == 'gate-failed':
+            raise OSError('gate unavailable')
+    monkeypatch.setattr(plugin_source_gate, 'write_state', gate)
+    if mode == 'save-failed':
+        def refuse(*args):
+            raise OSError('snapshot unavailable')
+        monkeypatch.setattr(os, 'replace', refuse)
+    monkeypatch.setattr(sys, 'argv', ['prepare_plugin_handoff.py', '--app-root', str(app),
+        '--java-project-root', str(tmp_path), '--type', 'reportlist', '--artifact', str(artifact),
+        '--form-number', 'uhyl_kpi_rpt', '--intent-file', str(intent), '--prepare-source'])
+    if mode == 'success':
+        module.main()
+    else:
+        with pytest.raises(SystemExit):
+            module.main()
+    outcome = json.loads(capsys.readouterr().out)
+    destination = app / '_runtime' / 'plugin-handoffs' / 'KpiReportPlugin.json'
+    assert list(destination.parent.glob('*.tmp')) == []
+    if mode in {'success', 'gate-failed'}:
+        assert len(calls) == 1
+        saved = json.loads(destination.read_text())
+        assert saved['handoff']['sourceGate']['requestedState'] == 'coding'
+        assert 'state' not in saved['handoff']['sourceGate']
+        assert outcome['status'] is (mode == 'success')
+        if mode == 'success':
+            assert outcome['sourcePreparation'] == {'state': 'coding', 'verified': True, 'path': saved['handoff']['sourceGate']['path']}
+            assert outcome['handoff']['sourceGate'] == saved['handoff']['sourceGate']
+        else:
+            assert outcome['errorCode'] == 'PLUGIN_SOURCE_GATE_UNAVAILABLE'
+            assert outcome['handoffPath'] == str(destination)
+            assert outcome['codingStartCommand'][-1] == str(destination)
+            assert outcome['gatePath'] == saved['handoff']['sourceGate']['path']
+            assert 'Do not probe' in outcome['recovery']
+        return
+    assert outcome['status'] is False and calls == []
+    if mode == 'changed-input':
+        assert outcome['errorCode'] == 'HANDOFF_INPUT_STALE'
+    assert not destination.exists()
+
+
+def test_report_refresh_requires_authoring_artifact_before_any_platform_lookup(tmp_path):
+    with pytest.raises(HandoffError) as error:
+        prepare_handoff(app_root=str(tmp_path), project_root=None, plugin_type='reportlist',
+            artifact_paths=[], refresh_report_state=True, intent={})
+    assert error.value.error_code == 'PLUGIN_REPORT_STATE_INPUT_INVALID'
+
+
+def _runtime_preparation_cli(tmp_path, monkeypatch, responses, *, external=None, operations=None, compile=False):
+    """Exercise real preparation and its child CLI using bounded native response snapshots."""
+    import prepare_plugin_handoff as module
+    app = tmp_path / 'app' / 't9k2_gl_ext'
+    _write(app / 'archive.json', {'appCode': 't9k2_gl_ext', 'appId': 'APP-ID'})
+    config = tmp_path / 'appconfig.json'
+    _write(config, {'compile': compile})
+    monkeypatch.setenv('KD_APPCONFIG', str(config))
+    fixture = tmp_path / 'responses.json'
+    _write(fixture, responses)
+    calls = tmp_path / 'calls.jsonl'
+    api = tmp_path / 'fixture_api.py'
+    api.write_text('import sys,json\nfrom pathlib import Path\n'
+        f'responses=json.loads(Path({str(fixture)!r}).read_text())\n'
+        f'with Path({str(calls)!r}).open("a") as f: f.write(json.dumps(sys.argv[1:])+"\\n")\n'
+        'flags=["--entityId","--keyword","--formNumber","--bizAppNumber","--bizAppId","--appNumber"]\n'
+        'flag=next(v for v in flags if v in sys.argv)\n'
+        'command=sys.argv[sys.argv.index("--output")+2]\n'
+        'value=responses[command+":"+sys.argv[sys.argv.index(flag)+1]]\n'
+        'Path(sys.argv[sys.argv.index("--output")+1]).write_text(json.dumps(value))\n')
+    monkeypatch.setattr(module, 'COSMIC_API', api)
+    intent = tmp_path / 'intent.json'
+    _write(intent, {'form': 't9k2_fetch_param', 'trigger': '处理前', 'className': 'FetchParameterPlugin',
+        'operationKeys': ['process'], 'coreLogic': ['按已确认的映射生成凭证'], 'specialized': {
+            'unresolvedDependencies': [], 'externalContracts': [
+                {'entity': 't9k2_gl_voucher_ext', 'fields': ['edescription', 'debitori']}] if external else []}})
+    args = ['prepare_plugin_handoff.py', '--app-root', str(app), '--project-root', str(_java_project(tmp_path)), '--type', 'operation',
+            '--form-number', 't9k2_fetch_param', '--intent-file', str(intent), '--prepare-source']
+    if external == 'file':
+        schema = tmp_path / 'voucher.schema.json'
+        _write(schema, _runtime_schema())
+        args.extend(['--external-schema', str(schema)])
+    if operations is not None:
+        opfile = tmp_path / 'operations.json'
+        _write(opfile, operations)
+        args.extend(['--operations-file', str(opfile)])
+    monkeypatch.setattr(sys, 'argv', args)
+    return module, app, calls, intent
+
+
+def _runtime_native(number='t9k2_fetch_param', app='gl'):
+    return {'status': True, 'data': json.dumps({'Name': number, 'DisplayName': '参数表',
+        'BizAppNumber': app, 'Properties': [{'_Type_': 'TextProp', 'Name': 'number', 'DisplayName': '编码'}]})}
+
+
+def _runtime_schema():
+    return {'status': True, 'data': {'formNumber': 't9k2_gl_voucher_ext', 'formName': '凭证扩展', 'entities': [
+        {'entityKey': 'entryentity', 'entityName': '凭证分录', 'fields': [
+            {'fieldKey': 'edescription', 'fieldName': '摘要', 'fieldType': 'TextField'},
+            {'fieldKey': 'debitori', 'fieldName': '原币借方', 'fieldType': 'AmountField'}]}]}}
+
+
+def _runtime_responses():
+    return {'getEntityType:t9k2_fetch_param': _runtime_native(),
+        'getApp:t9k2_gl_ext': {'status': True, 'data': {'appInfo': {'number': 't9k2_gl_ext', 'id': 'APP-ID', 'devType': '2', 'parentId': 'BASE-ID'}}},
+        'getApp:BASE-ID': {'status': True, 'data': {'appInfo': {'number': 'gl', 'id': 'BASE-ID'}}},
+        'queryFormsByApp:t9k2_gl_ext': {'status': True, 'queryScope': {'appNumber': 't9k2_gl_ext'}, 'data': []},
+        'queryFormsByApp:gl': {'status': True,
+            'queryScope': {'source': 'explicit', 'appNumber': 'gl', 'cloudNumber': None},
+            'data': [{'formNumber': 't9k2_fetch_param', 'appNumber': 'gl', 'appId': 'BASE-ID'}]},
+        'listOperations:t9k2_fetch_param': {'status': True,
+            'data': {'formNumber': 't9k2_fetch_param', 'operations': [{'operationKey': 'process'}]}}}
+
+
+def test_runtime_native_owner_does_not_restrict_selected_application(tmp_path, monkeypatch, capsys):
+    responses = _runtime_responses()
+    module, app, calls, _ = _runtime_preparation_cli(tmp_path, monkeypatch, responses)
+    module.main()
+    outcome = json.loads(capsys.readouterr().out)
+    assert outcome["status"] is True
+    saved = json.loads(Path(outcome["handoffPath"]).read_text())
+    assert saved["handoff"]["formGraph"]["formNumber"] == "t9k2_fetch_param"
+    assert saved["handoff"]["formGraph"]["appCode"] == "gl"
+    recorded = [json.loads(line) for line in calls.read_text().splitlines()]
+    assert not any("getApp" in call or "queryFormsByApp" in call for call in recorded)
+
+
+def test_runtime_metadata_cannot_substitute_another_form(tmp_path, monkeypatch, capsys):
+    responses = _runtime_responses()
+    responses["getEntityType:t9k2_fetch_param"] = _runtime_native("another_form", "gl")
+    module, app, calls, _ = _runtime_preparation_cli(tmp_path, monkeypatch, responses)
+    with pytest.raises(SystemExit):
+        module.main()
+    outcome = json.loads(capsys.readouterr().out)
+    assert outcome["status"] is False
+    assert outcome["errorCode"] == "PLUGIN_CONTEXT_INCOMPLETE"
+    assert not list(app.rglob("*Plugin.json"))
+
+
+@pytest.mark.parametrize('related', ['native', 'metadata-missing', 'auth-failed', 'transport-failed', 'wrong-schema'])
+def test_runtime_related_graph_only_falls_back_for_entity_metadata_miss(tmp_path, monkeypatch, capsys, related):
+    responses = _runtime_responses()
+    native = _runtime_native('t9k2_gl_voucher_ext')
+    native['data'] = json.dumps({'Name': 't9k2_gl_voucher_ext', 'DisplayName': '凭证扩展', 'BizAppNumber': 'gl',
+        'Properties': [{'Name': key, '_Type_': 'TextProp', 'DisplayName': key} for key in ['edescription', 'debitori']]})
+    responses['getEntityType:t9k2_gl_voucher_ext'] = native if related == 'native' else {
+        'status': False, 'errorCode': 'bos.entityMetaDataNotExist', 'message': '实体t9k2_gl_voucher_ext元数据不存在。'}
+    if related == 'auth-failed':
+        responses['getEntityType:t9k2_gl_voucher_ext'] = {'status': False, 'errorCode': 'AUTH_FAILED', 'message': '访问令牌无效'}
+    if related == 'transport-failed':
+        responses['getEntityType:t9k2_gl_voucher_ext'] = {'status': False, 'errorCode': 'CONNECTION_REFUSED', 'message': 'Connection refused'}
+    responses['getFormSchema:t9k2_gl_voucher_ext'] = _runtime_schema()
+    if related == 'wrong-schema':
+        responses['getFormSchema:t9k2_gl_voucher_ext']['data']['formNumber'] = 'another_form'
+    module, _app, calls, _ = _runtime_preparation_cli(tmp_path, monkeypatch, responses, external='read')
+    good = related in {'native', 'metadata-missing'}
+    if good:
+        module.main()
+    else:
+        with pytest.raises(SystemExit):
+            module.main()
+    outcome = json.loads(capsys.readouterr().out)
+    assert outcome['status'] is good
+    recorded = [json.loads(line) for line in calls.read_text().splitlines()]
+    assert sum('getFormSchema' in args for args in recorded) == (related in {'metadata-missing', 'wrong-schema'})
+    if good:
+        saved = json.loads(Path(outcome['handoffPath']).read_text())
+        assert saved['handoff']['specialized']['externalContracts'][0]['fields'] == ['edescription', 'debitori']
+        assert len(saved['handoff']['relatedForms']) == (related == 'native')
+    else:
+        assert outcome['errorCode'] == ('PLUGIN_EXTERNAL_CONTRACT_UNVERIFIED' if related == 'wrong-schema' else 'PLUGIN_EVIDENCE_READ_FAILED')
+
+
+def test_runtime_explicit_evidence_is_reused_and_inputs_remain_hash_bound(tmp_path, monkeypatch, capsys):
+    operations = _runtime_responses()['listOperations:t9k2_fetch_param']
+    module, _app, calls, _ = _runtime_preparation_cli(tmp_path, monkeypatch, _runtime_responses(), external='file', operations=operations)
+    module.main()
+    outcome = json.loads(capsys.readouterr().out)
+    assert outcome['status'] is True
+    recorded = [json.loads(line) for line in calls.read_text().splitlines()]
+    assert len(recorded) == 1  # only the current entity read; operation and related evidence supplied
+    saved = json.loads(Path(outcome['handoffPath']).read_text())
+    assert {Path(row['path']).name for row in saved['inputFiles']} >= {'intent.json', 'operations.json', 'voucher.schema.json'}
+    from query_plugin_handoff import validate_input_files
+    validate_input_files(saved)
+    _write(tmp_path / 'voucher.schema.json', {'status': False})
+    with pytest.raises(ValueError, match='changed'):
+        validate_input_files(saved)
+
+
+@pytest.mark.parametrize('invalid', ['operations', 'fields', 'compile'])
+def test_runtime_explicit_inputs_do_not_bypass_verification(tmp_path, monkeypatch, capsys, invalid):
+    operations = _runtime_responses()['listOperations:t9k2_fetch_param']
+    if invalid == 'operations':
+        operations['data']['formNumber'] = 'another_form'
+    module, app, _calls, intent = _runtime_preparation_cli(tmp_path, monkeypatch, _runtime_responses(),
+        external='file', operations=operations, compile=invalid == 'compile')
+    if invalid == 'fields':
+        data = json.loads(intent.read_text())
+        data['specialized']['externalContracts'][0]['fields'] = ['debit', 'credit', 'creditlocal']
+        _write(intent, data)
+    with pytest.raises(SystemExit):
+        module.main()
+    outcome = json.loads(capsys.readouterr().out)
+    assert outcome['status'] is False
+    assert not list(app.rglob('*Plugin.json'))
+    if invalid == 'fields':
+        assert all(key in outcome['message'] for key in ['debit', 'credit', 'creditlocal']), outcome
+    if invalid == 'compile':
+        assert outcome['errorCode'] == 'PLUGIN_SDK_ENVIRONMENT_UNVERIFIED'
+
+
+@pytest.mark.parametrize('explicit', [False, True])
+def test_runtime_invalid_operation_stops_before_external_reads(tmp_path, monkeypatch, capsys, explicit):
+    responses = _runtime_responses()
+    responses['listOperations:t9k2_fetch_param']['data']['operations'] = [
+        {'operationKey': 'close'}, {'operationKey': 'fetchsync', 'operationName': '开始同步', 'operationType': 'donothing'}]
+    operations = responses['listOperations:t9k2_fetch_param'] if explicit else None
+    module, _app, calls, intent = _runtime_preparation_cli(tmp_path, monkeypatch, responses, external='read', operations=operations)
+    data = json.loads(intent.read_text())
+    data['operationKeys'] = ['confirm']
+    _write(intent, data)
+    with pytest.raises(SystemExit):
+        module.main()
+    outcome = json.loads(capsys.readouterr().out)
+    assert outcome['status'] is False
+    assert 'confirm' in outcome['message'] and 'available operationKeys: close, fetchsync' in outcome['message']
+    recorded = [json.loads(line) for line in calls.read_text().splitlines()]
+    assert all('t9k2_gl_voucher_ext' not in args for args in recorded)
+    assert sum('listOperations' in args for args in recorded) == (not explicit)
+
+
+def test_external_diagnostics_collect_all_contracts_and_remain_bounded():
+    from prepare_plugin_handoff import _verify_external_contracts
+    catalog = [{'formNumber': 'voucher', 'entityKey': 'entryentity', 'entityName': '分录',
+                'fields': {'debitori': {'fieldKey': 'debitori', 'fieldName': '原币借方'}}}]
+    with pytest.raises(HandoffError) as error:
+        _verify_external_contracts([{'entity': 'voucher', 'fields': ['debit', 'credit']},
+                                    {'entity': 'account_mapping', 'fields': ['account']},
+                                    {'entity': 'org_mapping', 'fields': ['org']}], catalog)
+    assert error.value.error_code == 'PLUGIN_EXTERNAL_CONTRACT_UNVERIFIED'
+    assert all(value in str(error.value) for value in ['3 external contract(s)', 'debit', 'credit', 'account_mapping', 'org_mapping'])
+    with pytest.raises(HandoffError) as many:
+        _verify_external_contracts([{'entity': 'missing_' + str(index)} for index in range(40)], catalog)
+    assert '40 external contract(s)' in str(many.value)
+    assert '32 additional failed contracts omitted' in str(many.value)
+    assert len(str(many.value)) < 6500
+
+
+def test_explicit_external_schema_cannot_satisfy_another_form_with_same_entity_key():
+    from prepare_plugin_handoff import _verify_external_contracts
+    catalog = [{'formNumber': 'wrong_form', 'entityKey': 'entryentity', 'entityName': '分录',
+                'fields': {'debitori': {'fieldKey': 'debitori'}}}]
+    with pytest.raises(HandoffError):
+        _verify_external_contracts([{'entity': 'entryentity', 'formNumber': 'voucher', 'fields': ['debitori']}], catalog)
+
+
+def test_session_voucher_diagnostic_keeps_all_eleven_failed_selectors():
+    from prepare_plugin_handoff import _verify_external_contracts
+    missing = ["entries." + key for key in ["currency", "account", "debit", "credit", "localdebit",
+        "localcredit", "description", "seq", "t9k2_chargeperson", "t9k2_country", "t9k2_province"]]
+    catalog = [{"formNumber": "voucher", "entityKey": "entryentity", "fields": {
+        "debitori": {"fieldName": "原币借方"}, "edescription": {"fieldName": "摘要"}}}]
+    with pytest.raises(HandoffError) as error:
+        _verify_external_contracts([{"entity": "voucher", "fields": missing}], catalog)
+    assert all(selector in str(error.value) for selector in missing), str(error.value)
+    assert "unverified field selectors (11)" in str(error.value)
+    assert len(str(error.value)) < 1000
+
+
+def test_page_only_handoff_compiles_without_entity_fields(tmp_path, monkeypatch, capsys):
+    import prepare_plugin_handoff as module
+    import compile_plugin_source as compiler
+    from argparse import Namespace
+    from query_plugin_handoff import query
+
+    app = tmp_path / "app" / "sample_app"
+    _write(app / "archive.json", {"appCode": "sample_app", "appId": "SAMPLE-ID"})
+    project = _java_project(tmp_path)
+    config = tmp_path / "appconfig.json"
+    _write(config, {"compile": False})
+    monkeypatch.setenv("KD_APPCONFIG", str(config))
+    xml = """<FormMetadata><Key>sample_page</Key><Name>Filter Page</Name><BizAppNumber>sample_app</BizAppNumber><Items>
+      <BasedataFormAp><Plugins><Plugin><ClassName>kd.bos.app.sample.app.form.SamplePlugin</ClassName><Enabled>true</Enabled></Plugin></Plugins></BasedataFormAp>
+      <FormAp><Id>root</Id><Key>sample_page</Key></FormAp><FilterGridAp><Id>filter</Id><ParentId>root</ParentId><Key>filtergrid</Key></FilterGridAp>
+    </Items></FormMetadata>"""
+    calls = []
+    def read(app_root, command, selector, flag="--formNumber"):
+        calls.append((command, selector, flag))
+        assert command == "getFormMetadata"
+        return {"status": True, "data": xml}
+    monkeypatch.setattr(module, "read_platform", read)
+    source = project / "src/main/java/kd/bos/app/sample/app/form/SamplePlugin.java"
+    source.parent.mkdir(parents=True)
+    source.write_text("package kd.bos.app.sample.app.form;\nimport kd.bos.form.plugin.AbstractFormPlugin;\npublic class SamplePlugin extends AbstractFormPlugin {}\n")
+    intent = {"form": "sample_page", "trigger": "open", "metadataNeeds": ["form"],
+              "coreLogic": ["initialize the filter"], "ownershipMode": "modify", "sourcePath": str(source),
+              "scenes": ["control/filter-grid/filter-grid-set-value"],
+              "specialized": {"unresolvedDependencies": [], "externalContracts": []}}
+    monkeypatch.setattr(sys, "argv", ["prepare_plugin_handoff.py", "--app-root", str(app),
+        "--project-root", str(project), "--form-number", "sample_page", "--type", "form",
+        "--intent-json", json.dumps(intent), "--prepare-source"])
+    module.main()
+    prepared = json.loads(capsys.readouterr().out)
+    assert prepared["status"] is True
+    assert prepared["metadata"]["formCount"] == 1
+    assert prepared["metadata"]["forms"][0]["metadataSource"] == "getFormMetadata"
+    assert "entityCount" not in prepared["metadata"]["forms"][0]
+    assert "handoff.uiContext" in prepared["contextSections"] and "handoff.formGraph" not in prepared["contextSections"]
+    assert calls == [("getFormMetadata", "sample_page", "--formId")]
+    document = json.loads(Path(prepared["handoffPath"]).read_text())
+    handoff = document["handoff"]
+    assert "formGraph" not in handoff
+    assert handoff["uiContext"]["formNumber"] == "sample_page"
+    assert any(control["key"] == "filtergrid" for control in handoff["uiContext"]["controls"])
+    assert handoff["fqcn"] == "kd.bos.app.sample.app.form.SamplePlugin"
+    for operation in ("coding-start", "coding-context"):
+        view = query(document, Namespace(operation=operation))
+        assert view["uiContext"]["formNumber"] == "sample_page"
+        assert view["codingEvidence"]["scenes"][0].endswith("filter-grid-set-value.md")
+        assert "formGraph" not in view and "entities" not in view
+        assert "unverified" in view["entityEvidenceScope"]
+    context = compiler.compile_handoff(prepared["handoffPath"])
+    result = compiler.compile_source(project, source, "SamplePlugin", 30, app_root=app,
+        plugin_type="form", form_number=context["formNumber"], operation_keys=[],
+        description=context["description"], field_context=context)
+    assert result["status"] is True and result["compileSkipped"] is True
+    assert json.loads((app / "archive.json").read_text())["javas"][0]["formNumber"] == "sample_page"
+    import register_plugins as registration
+    monkeypatch.setattr(registration, "_load_config", lambda root: {"baseUrl": "https://example.test"})
+    sent = []
+    def post(*args, **kwargs):
+        sent.append(args[3])
+        return {"status": True, "data": {"success": True}}
+    monkeypatch.setattr(registration.kd_api, "post", post)
+    monkeypatch.setattr(registration.kd_api, "get", lambda *args, **kwargs: {"status": True, "data": [
+        {"className": "kd.bos.app.sample.app.form.SamplePlugin", "location": "BILL_FORM"}]})
+    monkeypatch.setattr(sys, "argv", ["register_plugins.py", "--app-root", str(app), "--verify"])
+    assert registration.main() == 0
+    registered = json.loads(capsys.readouterr().out)
+    assert registered["verification"]["status"] == "pass"
+    assert registered["results"][0]["verifiedHere"] is True
+    assert sent[0]["formNumber"] == "sample_page" and sent[0]["targetType"] == "BILL_FORM"
+
+
+@pytest.mark.parametrize("xml", ["", "<bad", "<FormMetadata><Key>other</Key><Items/></FormMetadata>",
+                                "<FormMetadata><Key>sample_page</Key></FormMetadata>"])
+def test_invalid_page_metadata_never_proves_an_empty_page(tmp_path, monkeypatch, xml):
+    import prepare_plugin_handoff as module
+    monkeypatch.setattr(module, "read_platform", lambda *args, **kwargs: {"status": True, "data": xml})
+    with pytest.raises(module.HandoffError) as error:
+        module.read_ui_context(str(tmp_path), "sample_page", "form")
+    assert error.value.error_code == "PLUGIN_CONTEXT_INCOMPLETE"
+
+
+def test_entity_selectors_cannot_skip_entity_metadata(tmp_path, monkeypatch, capsys):
+    import prepare_plugin_handoff as module
+    intent = {"form": "sample_page", "trigger": "open", "metadataNeeds": ["form"],
+              "coreLogic": ["read an entity field"], "entities": {"value": "field"},
+              "specialized": {"unresolvedDependencies": []}}
+    monkeypatch.setattr(sys, "argv", ["prepare_plugin_handoff.py", "--app-root", str(tmp_path),
+        "--project-root", str(tmp_path), "--form-number", "sample_page", "--type", "form",
+        "--intent-json", json.dumps(intent)])
+    with pytest.raises(SystemExit):
+        module.main()
+    assert json.loads(capsys.readouterr().out)["errorCode"] == "PLUGIN_CONTEXT_INCOMPLETE"
+
+
+def test_source_only_modify_requires_no_platform_metadata(tmp_path, monkeypatch, capsys):
+    import prepare_plugin_handoff as module
+    import compile_plugin_source as compiler
+    from argparse import Namespace
+    from query_plugin_handoff import query
+    app = tmp_path / "app" / "sample_app"
+    _write(app / "archive.json", {"appCode": "sample_app", "appId": "SAMPLE-ID"})
+    project = _java_project(tmp_path)
+    config = tmp_path / "appconfig.json"
+    _write(config, {"compile": False})
+    monkeypatch.setenv("KD_APPCONFIG", str(config))
+    source = project / "src/main/java/kd/bos/app/sample/app/service/SampleService.java"
+    source.parent.mkdir(parents=True)
+    source.write_text("package kd.bos.app.sample.app.service; public class SampleService {}")
+    def unexpected(*args, **kwargs):
+        raise AssertionError("source-only task must not read platform metadata")
+    monkeypatch.setattr(module, "read_platform", unexpected)
+    intent = {"trigger": "update service", "metadataNeeds": [], "coreLogic": ["improve service"],
+              "ownershipMode": "modify", "sourcePath": str(source),
+              "specialized": {"unresolvedDependencies": []}}
+    monkeypatch.setattr(sys, "argv", ["prepare_plugin_handoff.py", "--app-root", str(app),
+        "--project-root", str(project), "--type", "service", "--intent-json", json.dumps(intent), "--prepare-source"])
+    module.main()
+    prepared = json.loads(capsys.readouterr().out)
+    document = json.loads(Path(prepared["handoffPath"]).read_text())
+    handoff = document["handoff"]
+    assert handoff["formNumber"] == "" and "formGraph" not in handoff and "uiContext" not in handoff
+    for operation in ("coding-start", "coding-context"):
+        view = query(document, Namespace(operation=operation))
+        assert view["sourceContext"]["scope"] == "source-only" and "formGraph" not in view
+    context = compiler.compile_handoff(prepared["handoffPath"])
+    monkeypatch.setattr(sys, "argv", ["compile_plugin_source.py", "--handoff", prepared["handoffPath"]])
+    assert compiler.main() == 0
+    result = json.loads(capsys.readouterr().out)
+    assert result["status"] is True and result["compileSkipped"] is True
+    assert json.loads((app / "archive.json").read_text())["javas"][0]["formNumber"] == ""
+
+
+def test_list_context_keeps_list_plugin_binding_and_controls(tmp_path, monkeypatch):
+    import prepare_plugin_handoff as module
+    xml = """<FormMetadata><Key>sample_page</Key><Items><FormAp><Id>main</Id><Key>sample_page</Key></FormAp>
+      <ListMeta><FormMetadata><Key>sample_list</Key><Items><FormAp><Id>list</Id><Key>sample_list</Key>
+      <Plugins><Plugin><ClassName>example.ListPlugin</ClassName><Enabled>true</Enabled></Plugin></Plugins></FormAp>
+      <FilterGridAp><Id>filter</Id><ParentId>list</ParentId><Key>filtergrid</Key></FilterGridAp></Items></FormMetadata></ListMeta>
+    </Items></FormMetadata>"""
+    monkeypatch.setattr(module, "read_platform", lambda *args, **kwargs: {"status": True, "data": xml})
+    context = module.read_ui_context(str(tmp_path), "sample_page", "listform", include_list=True)
+    assert context["plugins"] == [{"className": "example.ListPlugin", "type": "listform"}]
+    assert any(control["key"] == "filtergrid" for control in context["controls"])
+
+
+def test_page_field_selector_uses_explicit_ui_binding_not_control_key(tmp_path, monkeypatch):
+    import prepare_plugin_handoff as module
+    app = tmp_path / "app" / "sample_app"
+    _write(app / "archive.json", {"appCode": "sample_app", "appId": "SAMPLE-ID"})
+    project = _java_project(tmp_path)
+    xml = """<FormMetadata><Key>sample_page</Key><Items><FormAp><Id>root</Id><Key>sample_page</Key></FormAp>
+      <TextFieldAp><Id>control</Id><ParentId>root</ParentId><Key>visible_control</Key><FieldKey>temporary_value</FieldKey></TextFieldAp>
+    </Items></FormMetadata>"""
+    monkeypatch.setattr(module, "read_platform", lambda *args, **kwargs: {"status": True, "data": xml})
+    context = module.read_ui_context(str(tmp_path), "sample_page", "form")
+    assert next(row for row in context["controls"] if row["key"] == "visible_control")["fieldKey"] == "temporary_value"
+    intent = {"form": "sample_page", "trigger": "open", "coreLogic": ["read temporary input"],
+        "fields": {"input": "temporary_value"}, "specialized": {"unresolvedDependencies": []}}
+    prepared = module.prepare_handoff(app_root=str(app), project_root=str(project), plugin_type="form",
+                                      intent=intent, artifact_paths=[], ui_context=context)["handoff"]
+    assert prepared["fields"] == {"input": "temporary_value"} and "formGraph" not in prepared
+    intent["fields"] = {"input": "visible_control"}
+    with pytest.raises(module.HandoffError):
+        module.prepare_handoff(app_root=str(app), project_root=str(project), plugin_type="form",
+                               intent=intent, artifact_paths=[], ui_context=context)
+
+
+def test_dynamic_form_ap_plugin_binding_is_discovered(tmp_path, monkeypatch):
+    import prepare_plugin_handoff as module
+    xml = """<FormMetadata><Key>sample_page</Key><Items><FormAp><Id>root</Id><Key>sample_page</Key>
+      <Plugins><Plugin><ClassName>example.DynamicPlugin</ClassName><Enabled>true</Enabled></Plugin></Plugins>
+      </FormAp></Items></FormMetadata>"""
+    monkeypatch.setattr(module, "read_platform", lambda *args, **kwargs: {"status": True, "data": xml})
+    context = module.read_ui_context(str(tmp_path), "sample_page", "form")
+    assert context["plugins"] == [{"className": "example.DynamicPlugin", "type": "form"}]
+    context = module.read_ui_context(str(tmp_path), "sample_page", "operation")
+    assert context["plugins"][0]["type"] == "form"
+
+
+def test_operation_without_field_dependency_reads_only_operation_and_ownership(tmp_path, monkeypatch, capsys):
+    import prepare_plugin_handoff as module
+    from argparse import Namespace
+    from query_plugin_handoff import query
+    app = tmp_path / "app" / "sample_app"
+    _write(app / "archive.json", {"appCode": "sample_app", "appId": "SAMPLE-ID"})
+    project = _java_project(tmp_path)
+    config = tmp_path / "appconfig.json"
+    _write(config, {"compile": False})
+    monkeypatch.setenv("KD_APPCONFIG", str(config))
+    calls = []
+    def read(app_root, command, selector, flag="--formNumber"):
+        calls.append(command)
+        if command == "getApp":
+            return {"status": True, "data": {"appInfo": {"number": "sample_app", "id": "SAMPLE-ID"}}}
+        if command == "listOperations":
+            return {"status": True, "data": {"formNumber": "sample_page", "operations": [{"operationKey": "submit"}]}}
+        if command == "queryFormsByApp":
+            return {"status": True, "queryScope": {"appNumber": "sample_app"},
+                    "data": [{"formNumber": "sample_page", "appNumber": "sample_app", "appId": "SAMPLE-ID"}]}
+        raise AssertionError(command)
+    monkeypatch.setattr(module, "read_platform", read)
+    intent = {"form": "sample_page", "trigger": "submit", "operationKeys": ["submit"],
+              "metadataNeeds": ["operate"], "coreLogic": ["validate operation context"],
+              "specialized": {"unresolvedDependencies": []}}
+    monkeypatch.setattr(sys, "argv", ["prepare_plugin_handoff.py", "--app-root", str(app),
+        "--project-root", str(project), "--form-number", "sample_page", "--type", "operation",
+        "--intent-json", json.dumps(intent), "--prepare-source"])
+    module.main()
+    result = json.loads(capsys.readouterr().out)
+    document = json.loads(Path(result["handoffPath"]).read_text())
+    assert calls == ["listOperations"]
+    assert "formGraph" not in document["handoff"]
+    view = query(document, Namespace(operation="coding-start"))
+    assert view["operationContext"]["source"] == "listOperations"
+    assert view["operationContracts"][0]["operationKey"] == "submit"
+
+
+def test_namespaced_page_metadata_preserves_identity_and_plugin(tmp_path, monkeypatch):
+    import prepare_plugin_handoff as module
+    xml = """<FormMetadata xmlns="urn:test"><Key>sample_page</Key><Items><FormAp><Id>root</Id><Key>sample_page</Key><Plugins><Plugin><ClassName>example.PagePlugin</ClassName></Plugin></Plugins></FormAp></Items></FormMetadata>"""
+    monkeypatch.setattr(module, "read_platform", lambda *args, **kwargs: {"status": True, "data": xml})
+    context = module.read_ui_context(str(tmp_path), "sample_page", "form")
+    assert context["formNumber"] == "sample_page"
+    assert context["plugins"][0]["className"] == "example.PagePlugin"
+
+
+def test_page_operation_reuses_explicit_operation_evidence_without_entity_read(tmp_path, monkeypatch, capsys):
+    import prepare_plugin_handoff as module
+    app = tmp_path / "app" / "sample_app"
+    _write(app / "archive.json", {"appCode": "sample_app", "appId": "SAMPLE-ID"})
+    project = _java_project(tmp_path)
+    config = tmp_path / "appconfig.json"
+    _write(config, {"compile": False})
+    monkeypatch.setenv("KD_APPCONFIG", str(config))
+    operations = tmp_path / "operations.json"
+    _write(operations, {"status": True, "data": {"formNumber": "sample_page", "appRoot": str(app),
+        "operations": [{"operationKey": "refresh", "operationName": "Refresh"}]}})
+    xml = """<FormMetadata><Key>sample_page</Key><BizAppNumber>sample_app</BizAppNumber><Items>
+      <FormAp><Id>root</Id><Key>sample_page</Key></FormAp></Items></FormMetadata>"""
+    calls = []
+    def read(app_root, command, selector, flag="--formNumber"):
+        calls.append(command)
+        assert command == "getFormMetadata"
+        return {"status": True, "data": xml}
+    monkeypatch.setattr(module, "read_platform", read)
+    intent = {"form": "sample_page", "trigger": "click", "metadataNeeds": ["form", "operate"],
+              "coreLogic": ["invoke the existing refresh operation"],
+              "specialized": {"unresolvedDependencies": []}}
+    monkeypatch.setattr(sys, "argv", ["prepare_plugin_handoff.py", "--app-root", str(app),
+        "--project-root", str(project), "--form-number", "sample_page", "--type", "form",
+        "--intent-json", json.dumps(intent), "--operations-file", str(operations), "--prepare-source"])
+    module.main()
+    result = json.loads(capsys.readouterr().out)
+    document = json.loads(Path(result["handoffPath"]).read_text())
+    assert calls == ["getFormMetadata"]
+    assert document["handoff"]["operationKeys"] == []
+    assert document["handoff"]["availableOperations"][0]["operationKey"] == "refresh"
+    assert "formGraph" not in document["handoff"]
+    assert any(item["path"] == str(operations) for item in document["inputFiles"])
+
+
+def test_source_only_uses_existing_package_without_application_identity(tmp_path, monkeypatch, capsys):
+    import prepare_plugin_handoff as module
+    app = tmp_path / "app" / "unbound"
+    app.mkdir(parents=True)
+    project = _java_project(tmp_path)
+    config = tmp_path / "appconfig.json"
+    _write(config, {"compile": False})
+    monkeypatch.setenv("KD_APPCONFIG", str(config))
+    source = project / "src/main/java/example/SampleService.java"
+    source.parent.mkdir(parents=True)
+    source.write_text("package example; public class SampleService {}")
+    def unexpected(*args, **kwargs):
+        raise AssertionError("source-only task must not read metadata")
+    monkeypatch.setattr(module, "read_platform", unexpected)
+    intent = {"trigger": "edit", "metadataNeeds": [], "coreLogic": ["edit existing service"],
+              "ownershipMode": "modify", "sourcePath": str(source), "specialized": {"unresolvedDependencies": []}}
+    monkeypatch.setattr(sys, "argv", ["prepare_plugin_handoff.py", "--app-root", str(app),
+        "--project-root", str(project), "--type", "service", "--intent-json", json.dumps(intent), "--prepare-source"])
+    module.main()
+    result = json.loads(capsys.readouterr().out)
+    handoff = json.loads(Path(result["handoffPath"]).read_text())["handoff"]
+    assert handoff["fqcn"] == "example.SampleService"
+    assert handoff["packagePathSource"] == "existing source declaration"
+    assert handoff["formNumber"] == ""
+
+
+def test_page_can_create_a_distinct_plugin_without_overwriting_registered_class(tmp_path):
+    from prepare_plugin_handoff import prepare_handoff, HandoffError
+    app = tmp_path / "app" / "sample_app"
+    _write(app / "archive.json", {"appCode": "sample_app", "appId": "SAMPLE-ID"})
+    project = _java_project(tmp_path)
+    context = {"formNumber": "sample_page", "formName": "sample_page", "source": "getFormMetadata",
+               "controls": [], "plugins": [{"className": "example.ExistingPlugin", "type": "form"}]}
+    intent = {"form": "sample_page", "trigger": "click", "className": "NewPlugin",
+              "ownershipMode": "create-new", "coreLogic": ["handle click"],
+              "specialized": {"unresolvedDependencies": []}}
+    result = prepare_handoff(app_root=str(app), project_root=str(project), plugin_type="form",
+                             intent=intent, artifact_paths=[], ui_context=context)
+    assert result["handoff"]["className"] == "NewPlugin"
+    assert result["evidence"]["registeredPluginClasses"] == ["example.ExistingPlugin"]
+    intent["className"] = "ExistingPlugin"
+    with pytest.raises(HandoffError) as error:
+        prepare_handoff(app_root=str(app), project_root=str(project), plugin_type="form",
+                        intent=intent, artifact_paths=[], ui_context=context)
+    assert error.value.error_code == "PLUGIN_OWNERSHIP_CONFLICT"
+
+
+def test_fieldless_page_uses_real_javac_and_native_compile_archive(tmp_path, monkeypatch, capsys):
+    import os
+    import shlex
+    import shutil
+    import subprocess
+    import zipfile
+    import prepare_plugin_handoff as module
+    import compile_plugin_source as compiler
+    javac = shutil.which("javac")
+    java = shutil.which("java")
+    if not javac or not java or not shutil.which("javap"):
+        pytest.skip("JDK tools unavailable")
+    app = tmp_path / "app" / "sample_app"
+    _write(app / "archive.json", {"appCode": "sample_app", "appId": "SAMPLE-ID"})
+    gradle = tmp_path / "gradle"
+    project = gradle / "code" / "sample"
+    (project / "src/main/java").mkdir(parents=True)
+    (gradle / "settings.gradle").write_text("include(':sample')\nproject(':sample').projectDir=new File('code/sample')\n")
+    sdk = tmp_path / "sdk"
+    lib = sdk / "mservice-cosmic/lib/bos"
+    lib.mkdir(parents=True)
+    stub = tmp_path / "AbstractFormPlugin.java"
+    stub.write_text("package kd.bos.form.plugin; public abstract class AbstractFormPlugin {}")
+    subprocess.run([javac, "-d", str(tmp_path / "sdk-classes"), str(stub)], check=True, capture_output=True)
+    jar = lib / "fixture.jar"
+    with zipfile.ZipFile(jar, "w") as archive:
+        archive.write(tmp_path / "sdk-classes/kd/bos/form/plugin/AbstractFormPlugin.class",
+                      "kd/bos/form/plugin/AbstractFormPlugin.class")
+    (gradle / "gradle.properties").write_text(f"systemProp.cosmic_home={sdk}\n")
+    (gradle / "config.gradle").write_text('cosmic_libs_path="${cosmic_home}/mservice-cosmic/lib"\nbos="${cosmic_libs_path}/bos"')
+    config = tmp_path / "appconfig.json"
+    import re
+    settings = subprocess.run([java, "-XshowSettings:properties", "-version"], capture_output=True, text=True, timeout=15, check=True)
+    match = re.search(r"(?m)^\s*java\.home\s*=\s*(.+)$", settings.stderr + settings.stdout)
+    if not match:
+        pytest.skip("Java home cannot be resolved")
+    _write(config, {"compile": True, "GRADLE_ROOT": str(gradle), "JAVA_HOME": match.group(1).strip()})
+    monkeypatch.setenv("KD_APPCONFIG", str(config))
+    source = project / "src/main/java/kd/bos/app/sample/app/form/PagePlugin.java"
+    output = project / "build/classes/java/main"
+    wrapper = gradle / ("gradlew.bat" if os.name == "nt" else "gradlew")
+    if os.name == "nt":
+        wrapper.write_text(f'@echo off\nif not exist "{output}" mkdir "{output}"\n"{javac}" -cp "{jar}" -d "{output}" "{source}"\n')
+    else:
+        wrapper.write_text('#!/bin/sh\nset -e\nmkdir -p ' + shlex.quote(str(output)) + '\nexec ' +
+                           ' '.join(shlex.quote(str(value)) for value in (javac, '-cp', jar, '-d', output, source)) + '\n')
+        wrapper.chmod(0o755)
+    xml = """<FormMetadata><Key>sample_page</Key><BizAppNumber>sample_app</BizAppNumber>
+      <Items><FormAp><Id>root</Id><Key>sample_page</Key></FormAp></Items></FormMetadata>"""
+    monkeypatch.setattr(module, "read_platform", lambda *args, **kwargs: {"status": True, "data": xml})
+    intent = {"form": "sample_page", "trigger": "open", "metadataNeeds": ["form"], "className": "PagePlugin",
+              "coreLogic": ["initialize page"], "specialized": {"unresolvedDependencies": []}}
+    monkeypatch.setattr(sys, "argv", ["prepare_plugin_handoff.py", "--app-root", str(app), "--project-root", str(project),
+        "--form-number", "sample_page", "--type", "form", "--intent-json", json.dumps(intent), "--prepare-source"])
+    module.main()
+    prepared = json.loads(capsys.readouterr().out)
+    assert prepared["status"] is True
+    source.write_text("package kd.bos.app.sample.app.form; import kd.bos.form.plugin.AbstractFormPlugin; public class PagePlugin extends AbstractFormPlugin {}")
+    monkeypatch.setattr(sys, "argv", ["compile_plugin_source.py", "--handoff", prepared["handoffPath"], "--timeout-sec", "20"])
+    assert compiler.main() == 0
+    result = json.loads(capsys.readouterr().out)
+    assert result["compileSkipped"] is False
+    assert result["compiledArtifact"]["fqcn"] == "kd.bos.app.sample.app.form.PagePlugin"
+    assert json.loads((app / "archive.json").read_text())["javas"][0]["compileStatus"] == "passed"
+
+
+def test_page_and_entity_reads_run_independently_in_parallel(tmp_path, monkeypatch, capsys):
+    import threading
+    import prepare_plugin_handoff as module
+    app = tmp_path / "app" / "sample_app"
+    _write(app / "archive.json", {"appCode": "sample_app", "appId": "SAMPLE-ID"})
+    project = _java_project(tmp_path)
+    barrier = threading.Barrier(2)
+    calls = []
+    xml = "<FormMetadata><Key>sample_page</Key><BizAppNumber>sample_app</BizAppNumber><Items><FormAp><Id>root</Id><Key>sample_page</Key></FormAp></Items></FormMetadata>"
+    def read(app_root, command, selector, flag="--formNumber"):
+        calls.append(command)
+        barrier.wait(timeout=5)
+        if command == "getFormMetadata":
+            return {"status": True, "data": xml}
+        if command == "getEntityType":
+            return {"status": True, "data": {"Name": "sample_page", "BizAppNumber": "sample_app",
+                "Properties": [{"Name": "amount", "_Type_": "DecimalProp"}]}}
+        raise AssertionError(command)
+    monkeypatch.setattr(module, "read_platform", read)
+    intent = {"form": "sample_page", "trigger": "change", "metadataNeeds": ["form", "entity"],
+              "fields": {"amount": "amount"}, "coreLogic": ["update the amount"],
+              "specialized": {"unresolvedDependencies": []}}
+    monkeypatch.setattr(sys, "argv", ["prepare_plugin_handoff.py", "--app-root", str(app),
+        "--project-root", str(project), "--form-number", "sample_page", "--type", "form",
+        "--intent-json", json.dumps(intent)])
+    module.main()
+    result = json.loads(capsys.readouterr().out)
+    saved = json.loads(Path(result["handoffPath"]).read_text())["handoff"]
+    assert sorted(calls) == ["getEntityType", "getFormMetadata"]
+    assert saved["uiContext"]["formNumber"] == "sample_page"
+    assert saved["formGraph"]["entities"][0]["fields"][0]["fieldKey"] == "amount"
+
+
+def test_cli_without_selected_java_directory_stops_before_platform_reads(tmp_path, monkeypatch, capsys):
+    import prepare_plugin_handoff as module
+    app = tmp_path / "app"
+    _write(app / "archive.json", {"appCode": "sample_app"})
+    monkeypatch.setattr(module, "read_platform", lambda *args, **kwargs: pytest.fail("unexpected platform read"))
+    monkeypatch.setattr(sys, "argv", ["prepare_plugin_handoff.py", "--app-root", str(app), "--form-number", "sample_form", "--type", "form", "--intent-json", json.dumps({"coreLogic": ["test"]})])
+    with pytest.raises(SystemExit):
+        module.main()
+    result = json.loads(capsys.readouterr().out)
+    assert result["errorCode"] == "PLUGIN_WORKSPACE_UNRESOLVED"
+    assert "ask the user" in result["message"]
+
+
+def test_explicit_source_directory_is_used_exactly_and_cannot_escape_module(tmp_path):
+    project = _java_project(tmp_path / "module")
+    chosen = project / "src" / "main" / "java" / "example" / "custom"
+    result = resolve_output_path(str(tmp_path / "app"), "billform", str(project), source_directory=str(chosen))
+    assert result["packagePath"] == "example/custom"
+    assert result["outputDir"] == "src/main/java/example/custom"
+    outside = resolve_output_path(str(tmp_path / "app"), "billform", str(project), source_directory=str(tmp_path / "outside"))
+    assert outside["errorCode"] == "PLUGIN_WORKSPACE_UNRESOLVED"
+
+
+def test_user_selected_package_is_prepared_without_project_search(tmp_path, monkeypatch, capsys):
+    module, app, calls, intent_file = _runtime_preparation_cli(tmp_path, monkeypatch, _runtime_responses())
+    chosen = tmp_path / "src" / "main" / "java" / "example" / "chosen"
+    intent = json.loads(intent_file.read_text())
+    intent["sourceDirectory"] = str(chosen)
+    _write(intent_file, intent)
+    argv = sys.argv.copy()
+    index = argv.index("--project-root")
+    del argv[index:index + 2]
+    monkeypatch.setattr(sys, "argv", argv)
+    original_rglob = Path.rglob
+    def check_search(path, *args, **kwargs):
+        if path == tmp_path or tmp_path in path.parents:
+            pytest.fail("unexpected project search")
+        return original_rglob(path, *args, **kwargs)
+    monkeypatch.setattr(Path, "rglob", check_search)
+    module.main()
+    outcome = json.loads(capsys.readouterr().out)
+    assert outcome["status"] is True
+    assert Path(outcome["handoff"]["sourcePath"]).parent == chosen
+    assert outcome["handoff"]["packagePath"] == "example/chosen"
+
+
+def test_integer_field_context_contains_sdk_accessor_and_nullable_boundary():
+    from prepare_plugin_handoff import _field_contract
+    value = _field_contract({"fieldKey": "quantity", "fieldName": "Quantity", "fieldType": "IntegerProp"})
+    assert value["valueAccessor"] == 'getInt("quantity")'
+    assert value["javaType"] == "Integer"
+    assert "raw value" in value["note"]
+
+
+def test_selected_java_source_root_uses_convention_without_project_search(tmp_path, monkeypatch):
+    project = _java_project(tmp_path / "module")
+    app = tmp_path / "app" / "sample_demo"
+    _write(app / "archive.json", {"appCode": "sample_demo"})
+    monkeypatch.setattr(Path, "rglob", lambda *args, **kwargs: pytest.fail("unexpected project search"))
+    result = resolve_output_path(str(app), "operation", str(project), source_directory=str(project / "src/main/java"))
+    assert result["errorCode"] == "0"
+    assert result["packagePath"] == "kd/bos/app/sample/demo/operate"