@shundoo-ai/dsh-cosmic 1.0.21 → 1.0.22

package/skills/cosmic-build/skills/cosmic-meta-api/scripts/test/test_report_plugin_contract.py

@@ -42,16 +42,68 @@ def _column(field_key, field_type="decimal", presentation=None, date_index=None)
     return column
 
 
-def _compile(columns=(), filters=(), plugins=(("kd.kdtest.report.P", "Java"),)):
-    normalized_columns = report_ops.normalize_report_columns_input(list(columns)) if columns else []
+def _compile_requirements(columns=(), filters=(), plugins=(("kd.kdtest.report.P", "Java"),)):
+    """仅测试原始/历史需求编译；此路径不证明输入可写，也不调用 writer。"""
     normalized_filters = report_ops.normalize_report_filters_input(list(filters)) if filters else []
     return report_ops.compile_report_plugin_contract({
-        "reportColumns": normalized_columns,
+        "reportColumns": list(columns),
         "reportFilters": normalized_filters,
         "reportPlugins": [{"className": name, "type": kind} for name, kind in plugins],
     }, "kdtest_rpt")
 
 
+class DefaultSortContractTest(unittest.TestCase):
+    def _artifact(self):
+        return {
+            "reportColumns": [{"kind": "group", "fieldKey": "group", "caption": "Group",
+                               "children": [_column("created", "date", date_index="CreateTime"),
+                                            _column("amount")]}],
+            "reportSorts": [{"fieldKey": "created", "direction": "desc"},
+                            {"fieldKey": "amount", "direction": "asc"}],
+            "reportPlugins": [{"className": "kd.test.report.P", "type": "Java", "enabled": True}],
+        }
+
+    def test_order_and_dataset_alias_reach_query_contract(self):
+        artifact = self._artifact()
+        contract = report_ops.compile_report_plugin_contract(artifact, "kdtest_rpt")
+        self.assertEqual(contract["defaultSorts"], [
+            {"fieldKey": "created", "dateIndex": "CreateTime", "direction": "desc"},
+            {"fieldKey": "amount", "dateIndex": "amount", "direction": "asc"},
+        ])
+        self.assertEqual(contract["defaultSortPolicy"]["priority"], "interactiveThenDefault")
+        self.assertFalse(contract["defaultSortPolicy"]["metadataWritten"])
+        self.assertFalse(contract["defaultSortPolicy"]["runtimeVerified"])
+        self.assertNotIn("dateIndex", artifact["reportSorts"][0])
+
+    def test_missing_or_group_sort_reference_fails(self):
+        for key in ("missing", "group"):
+            with self.subTest(key=key):
+                artifact = self._artifact()
+                artifact["reportSorts"][0]["fieldKey"] = key
+                with self.assertRaisesRegex(ValueError, "sort columns not found"):
+                    report_ops.compile_report_default_sorts(artifact)
+
+    def test_missing_dataset_binding_is_an_input_error(self):
+        artifact = self._artifact()
+        del artifact["reportColumns"][0]["children"][0]["dateIndex"]
+        with self.assertRaisesRegex(ValueError, "dateIndex"):
+            report_ops.compile_report_default_sorts(artifact)
+
+    def test_sorting_requires_one_enabled_java_fetch_plugin(self):
+        for plugins in ([], [{"className": "P", "type": "JS"}],
+                        [{"className": "P", "type": "KingScript"}],
+                        [{"className": "P", "enabled": False}],
+                        [{"className": "P"}, {"className": "Q"}]):
+            with self.subTest(plugins=plugins):
+                artifact = self._artifact()
+                artifact["reportPlugins"] = plugins
+                artifact["queryDataSource"] = {"dataSourceNumber": "ds"}
+                with self.assertRaisesRegex(ValueError, "REPORT_DEFAULT_SORT_PLUGIN_REQUIRED"):
+                    report_ops.compile_report_default_sorts(artifact)
+                artifact.pop("reportSorts")
+                self.assertEqual(report_ops.compile_report_default_sorts(artifact), [])
+
+
 class PresentationInputContractTest(unittest.TestCase):
     """Presentation is validated against the column it decorates."""
 
@@ -97,11 +149,107 @@ class PresentationInputContractTest(unittest.TestCase):
         self.assertIn("scale must be an integer", self._reject(
             _column("amt", presentation={"kind": "decimal", "scale": 42})))
 
-    def test_a_valid_presentation_survives_normalization(self):
+    def test_an_explicit_decimal_presentation_survives_normalization(self):
         columns = report_ops.normalize_report_columns_input([
-            _column("amt", presentation={"kind": "amount", "currencyField": "cur", "scale": 2})])
-        self.assertEqual(columns[0]["presentation"],
-                         {"kind": "amount", "currencyField": "cur", "scale": 2})
+            _column("value", presentation={"kind": "decimal", "scale": 2})])
+        self.assertEqual(columns[0]["presentation"], {"kind": "decimal", "scale": 2})
+
+
+class DynamicPrecisionWriteGuardTest(unittest.TestCase):
+    """测试真实门禁和入口；HTTP/auth 仅作不应触达的边界探针。"""
+
+    def _columns(self, kind="amount", field_type="bigint", hide=True, nested=False, scale=None):
+        key = "measureUnitField" if kind == "qty" else "currencyField"
+        spec = {"kind": kind, key: "reference"}
+        if scale is not None:
+            spec["scale"] = scale
+        columns = [_column("value", presentation=spec),
+                   {**_column("reference", field_type), "hide": hide}]
+        return [{"kind": "group", "fieldKey": "group", "caption": "Group", "children": columns}] if nested else columns
+
+    def test_scalar_targets_never_prove_a_precision_reference(self):
+        import copy
+        for kind in ("amount", "price", "qty"):
+            for field_type in report_ops._REPORT_COLUMN_FIELD_TYPES:
+                for hide in (True, False):
+                    for nested in (True, False):
+                        for scale in (None, 2):
+                            with self.subTest(kind=kind, fieldType=field_type, hide=hide, nested=nested, scale=scale):
+                                columns = self._columns(kind, field_type, hide, nested, scale)
+                                before = copy.deepcopy(columns)
+                                with self.assertRaisesRegex(ValueError, "REPORT_PRECISION_REFERENCE_UNVERIFIED"):
+                                    report_ops.normalize_report_columns_input(columns)
+                                self.assertEqual(columns, before)
+
+    def test_direct_writers_and_dry_run_refuse_before_http(self):
+        from unittest import mock
+        with mock.patch.object(report_ops, "_api_call") as http:
+            for writer in (report_ops.set_report_columns, report_ops.add_report_columns):
+                for dry_run in (True, False):
+                    with self.subTest(writer=writer.__name__, dry_run=dry_run):
+                        with self.assertRaisesRegex(ValueError, "REPORT_PRECISION_REFERENCE_UNVERIFIED"):
+                            writer({}, "fixture", "FID", self._columns(nested=True), dry_run=dry_run)
+            http.assert_not_called()
+
+    def test_serve_and_pipeline_refuse_before_writers(self):
+        import cosmic_api
+        from unittest import mock
+        for kind in ("amount", "price", "qty"):
+            with mock.patch.object(cosmic_api, "do_set_report_columns") as write, \
+                    mock.patch.object(cosmic_api, "do_add_report_columns") as append, \
+                    mock.patch.object(cosmic_api, "do_create_page") as create:
+                for cmd in ("setReportColumns", "addReportColumns"):
+                    with self.assertRaisesRegex(ValueError, "REPORT_PRECISION_REFERENCE_UNVERIFIED"):
+                        cosmic_api._dispatch_serve({}, "fixture", cmd, {"columns": self._columns(kind)})
+                with self.assertRaisesRegex(ValueError, "REPORT_PRECISION_REFERENCE_UNVERIFIED"):
+                    cosmic_api._execute_report_pipeline({}, "fixture", {"reportColumns": self._columns(kind)}, "APP", "UNIT")
+                write.assert_not_called()
+                append.assert_not_called()
+                create.assert_not_called()
+
+    def test_raw_contract_keeps_requirement_without_claiming_runtime_success(self):
+        import copy
+        for kind in ("amount", "price", "qty"):
+            columns = self._columns(kind)
+            artifact = {"reportColumns": columns, "reportSorts": [{"fieldKey": "value", "direction": "asc"}],
+                        "reportPlugins": [{"className": "kd.test.report.P", "type": "Java", "enabled": True}]}
+            before = copy.deepcopy(artifact)
+            contract = report_ops.compile_report_plugin_contract(artifact)
+            self.assertEqual(artifact, before)
+            self.assertEqual(contract["defaultSorts"], [{"fieldKey": "value", "dateIndex": "value", "direction": "asc"}])
+            entry = contract["columnPresentation"][0]
+            source = entry["precisionSource"]
+            self.assertEqual(source["requiredRuntimeValueType"], "DynamicObject")
+            self.assertEqual(source["fieldKey"], "reference")
+            self.assertFalse(source["rawIdIsReference"])
+            self.assertFalse(source["runtimeVerified"])
+            self.assertTrue(source["metadataWriteBlocked"])
+            self.assertEqual(len(source["requiredEvidence"]), 3)
+            self.assertEqual(columns[0]["presentation"]["kind"], kind)
+
+    def test_dynamic_precision_cannot_refresh_a_successful_authoring_baseline(self):
+        from unittest import mock
+        with tempfile.TemporaryDirectory() as root:
+            report_ops.write_report_authoring_state(root, "sample_rpt", "FID",
+                {"reportColumns": [_column("value")]}, {"reportColumns": [_column("value")]})
+            path = report_ops.report_authoring_path(root, "sample_rpt")
+            before = path.read_bytes()
+            for kind in ("amount", "price", "qty"):
+                with mock.patch.object(report_ops, "_api_call") as http:
+                    with self.assertRaisesRegex(ValueError, "REPORT_PRECISION_REFERENCE_UNVERIFIED"):
+                        report_ops.write_report_authoring_state(root, "sample_rpt", "FID",
+                            {"reportColumns": self._columns(kind)}, {})
+                    http.assert_not_called()
+                self.assertEqual(path.read_bytes(), before)
+
+    def test_supported_unbound_types_are_not_precision_fallbacks(self):
+        columns = [_column("id", "bigint"), _column("date", "date"),
+                   _column("measure", presentation={"kind": "decimal", "scale": 3}),
+                   _column("ref", "bigint", {"kind": "basedata", "entityId": "bd_item", "displayProp": "name"})]
+        normalized = report_ops.normalize_report_columns_input(columns)
+        self.assertEqual(normalized, columns)
+        for entry in _compile_requirements(columns=normalized)["columnPresentation"]:
+            self.assertNotIn("precisionSource", entry)
 
 
 class PresentationStaysOutOfPlatformPayloadTest(unittest.TestCase):
@@ -109,14 +257,14 @@ class PresentationStaysOutOfPlatformPayloadTest(unittest.TestCase):
 
     def test_column_payload_carries_only_contract_properties(self):
         columns = report_ops.normalize_report_columns_input([
-            _column("amt", presentation={"kind": "amount", "currencyField": "cur", "scale": 2})])
+            _column("value", presentation={"kind": "decimal", "scale": 2})])
         payload = report_ops._build_columns_payload(columns)
         self.assertEqual(sorted(payload[0]), ["caption", "dateIndex", "fieldKey", "fieldType", "kind"])
 
     def test_nested_group_children_are_also_clean(self):
         columns = report_ops.normalize_report_columns_input([{
             "kind": "group", "fieldKey": "grp", "caption": "G", "children": [
-                _column("qty", presentation={"kind": "qty", "measureUnitField": "unit"})]}])
+                _column("value", presentation={"kind": "decimal", "scale": 3})]}])
         child = report_ops._build_columns_payload(columns)[0]["children"][0]
         self.assertNotIn("presentation", child)
         self.assertNotIn("measureUnitField", child)
@@ -132,13 +280,13 @@ class CompileReportPluginContractTest(unittest.TestCase):
         report handed Java delivery nothing at all, and a date column returned as text then
         failed at render time with "setvalue fail, name: <column>, Unparseable date".
         """
-        contract = _compile(columns=[_column("amt")])
+        contract = _compile_requirements(columns=[_column("amt")])
         self.assertIsNotNone(contract)
         self.assertEqual(contract["columnPresentation"], [])
         self.assertEqual([row["dateIndex"] for row in contract["dataSetColumnTypes"]], ["amt"])
 
     def test_nothing_to_say_still_means_no_contract(self):
-        self.assertIsNone(_compile(columns=[]))
+        self.assertIsNone(_compile_requirements(columns=[]))
 
     def test_each_kind_maps_to_a_documented_factory_call(self):
         cases = {
@@ -156,11 +304,11 @@ class CompileReportPluginContractTest(unittest.TestCase):
         }
         for kind, (spec, field_type, expected) in cases.items():
             with self.subTest(kind=kind):
-                contract = _compile(columns=[_column("amt", field_type, presentation=spec)])
+                contract = _compile_requirements(columns=[_column("amt", field_type, presentation=spec)])
                 self.assertEqual(contract["columnPresentation"][0]["java"], expected)
 
     def test_no_guessed_type_constant_appears_anywhere(self):
-        contract = _compile(columns=[
+        contract = _compile_requirements(columns=[
             _column("amt", presentation={"kind": "amount", "currencyField": "cur"}),
             _column("qty", presentation={"kind": "qty", "measureUnitField": "unit"}),
         ])
@@ -169,7 +317,7 @@ class CompileReportPluginContractTest(unittest.TestCase):
             self.assertNotIn(guessed, rendered)
 
     def test_scale_on_a_money_column_is_executable_code_not_a_comment(self):
-        entry = _compile(columns=[
+        entry = _compile_requirements(columns=[
             _column("amt", presentation={"kind": "amount", "currencyField": "cur", "scale": 2}),
         ])["columnPresentation"][0]
         self.assertEqual(entry["javaFollowUp"], ["setScale(2)"])
@@ -177,7 +325,7 @@ class CompileReportPluginContractTest(unittest.TestCase):
         self.assertNotIn("/*", entry["java"])
 
     def test_a_plain_decimal_column_takes_scale_from_the_factory(self):
-        entry = _compile(columns=[
+        entry = _compile_requirements(columns=[
             _column("qty", presentation={"kind": "decimal", "scale": 4}),
         ])["columnPresentation"][0]
         self.assertIn(", 4)", entry["java"])
@@ -191,20 +339,20 @@ class CompileReportPluginContractTest(unittest.TestCase):
         R-presentation-binding now rejects an undeclared target — would only ever be reachable
         from an artifact the validator refuses.
         """
-        contract = _compile(columns=[
+        contract = _compile_requirements(columns=[
             _column("amt", presentation={"kind": "amount", "currencyField": "currency_id"}),
             _column("qty", presentation={"kind": "qty", "measureUnitField": "unit_id"}),
         ])
         self.assertEqual(contract["dataSetColumns"], ["amt", "qty"])
 
     def test_group_children_are_compiled_too(self):
-        contract = _compile(columns=[{
+        contract = _compile_requirements(columns=[{
             "kind": "group", "fieldKey": "grp", "caption": "G", "children": [
                 _column("amt", presentation={"kind": "amount", "currencyField": "cur"})]}])
         self.assertEqual(contract["columnPresentation"][0]["fieldKey"], "amt")
 
     def test_unpersisted_filter_properties_become_requirements(self):
-        contract = _compile(
+        contract = _compile_requirements(
             columns=[_column("amt")],
             filters=[{"fieldPath": "flt_date", "displayName": "Date", "compare": "between",
                       "mustInput": True, "defaultValue": "thismonth"}],
@@ -220,7 +368,7 @@ class CompileReportPluginContractTest(unittest.TestCase):
         between date filter does not become a date-range control. Before this entry existed the
         comparison reached Java delivery as nothing.
         """
-        contract = _compile(
+        contract = _compile_requirements(
             columns=[_column("amt")],
             filters=[
                 {"fieldPath": "flt_date", "displayName": "Date", "compare": "between"},
@@ -260,7 +408,7 @@ class CompileReportPluginContractTest(unittest.TestCase):
         self.assertEqual(contract["filterValueContracts"][0]["candidateValueKeys"], ["acme_region", "flt_area", "acme_area"])
 
     def test_default_valued_filter_properties_are_not_requirements(self):
-        contract = _compile(
+        contract = _compile_requirements(
             columns=[_column("amt")],
             filters=[{"fieldPath": "flt_date", "displayName": "Date", "compare": "between",
                       "mustInput": False, "visible": True}],
@@ -285,17 +433,17 @@ class CompileReportPluginContractTest(unittest.TestCase):
         }
         for field_type, (accessor, java_type, algo_type) in expected.items():
             with self.subTest(fieldType=field_type):
-                row = _compile(columns=[_column("col", field_type=field_type)])[
+                row = _compile_requirements(columns=[_column("col", field_type=field_type)])[
                     "dataSetColumnTypes"][0]
                 self.assertEqual(row["rowAccessor"], accessor)
                 self.assertEqual(row["javaType"], java_type)
                 self.assertEqual(row["algoDataType"], algo_type)
-        decimal = _compile(columns=[_column("amt")])["dataSetColumnTypes"][0]
+        decimal = _compile_requirements(columns=[_column("amt")])["dataSetColumnTypes"][0]
         self.assertEqual(decimal["rowAccessor"], "getBigDecimal")
         self.assertTrue(decimal["algoDataType"].startswith("DataType.createBigDecimalType("))
 
     def test_a_formula_column_is_not_given_a_guessed_type(self):
-        row = _compile(columns=[_column("calc", field_type="formula")])["dataSetColumnTypes"][0]
+        row = _compile_requirements(columns=[_column("calc", field_type="formula")])["dataSetColumnTypes"][0]
         self.assertEqual(row["rowAccessor"], "get")
         self.assertEqual(row["javaType"], "Object")
         self.assertNotIn("algoDataType", row)
@@ -317,7 +465,7 @@ class CompileReportPluginContractTest(unittest.TestCase):
         platform cannot render: the runtime entity is built from the column list, so a value
         arriving outside any column has no property to attach to.
         """
-        contract = _compile(columns=[
+        contract = _compile_requirements(columns=[
             _column("cur", field_type="bigint"),
             _column("amt", presentation={"kind": "amount", "currencyField": "cur"}),
         ])
@@ -348,13 +496,13 @@ class CompileReportPluginContractTest(unittest.TestCase):
         self.assertNotIn("unit", contract["dataSetColumns"])
 
     def test_a_kind_that_binds_nothing_reports_no_binding(self):
-        contract = _compile(columns=[
+        contract = _compile_requirements(columns=[
             _column("sup", field_type="bigint", presentation={
                 "kind": "basedata", "entityId": "bd_supplier", "displayProp": "name"})])
         self.assertNotIn("bindsTo", contract["columnPresentation"][0])
 
     def test_one_binding_target_lists_every_column_that_needs_it(self):
-        contract = _compile(columns=[
+        contract = _compile_requirements(columns=[
             _column("unit", field_type="bigint"),
             _column("in_qty", presentation={"kind": "qty", "measureUnitField": "unit"}),
             _column("out_qty", presentation={"kind": "qty", "measureUnitField": "unit"}),
@@ -364,11 +512,11 @@ class CompileReportPluginContractTest(unittest.TestCase):
         self.assertEqual(contract["dataSetColumns"].count("unit"), 1)
 
     def test_a_column_nothing_binds_to_carries_no_back_reference(self):
-        contract = _compile(columns=[_column("amt")])
+        contract = _compile_requirements(columns=[_column("amt")])
         self.assertNotIn("requiredBy", contract["dataSetColumnTypes"][0])
 
     def test_a_grouped_column_is_typed_like_any_other(self):
-        contract = _compile(columns=[{
+        contract = _compile_requirements(columns=[{
             "kind": "group", "fieldKey": "grp", "caption": "G",
             "children": [_column("biz_date", field_type="date")]}])
         self.assertEqual(
@@ -377,7 +525,7 @@ class CompileReportPluginContractTest(unittest.TestCase):
 
     def test_a_column_whose_key_differs_from_its_dataset_column_keeps_the_binding(self):
         """No factory signature takes dateIndex, so setDateIndex has to be emitted."""
-        contract = _compile(columns=[{
+        contract = _compile_requirements(columns=[{
             "kind": "column", "fieldKey": "material_ref", "dateIndex": "material_id",
             "fieldType": "bigint", "caption": "Material",
             "presentation": {"kind": "basedata", "entityId": "bd_material",
@@ -386,23 +534,60 @@ class CompileReportPluginContractTest(unittest.TestCase):
                          ['setDateIndex("material_id")'])
 
     def test_a_column_whose_key_equals_its_dataset_column_gets_no_redundant_setter(self):
-        contract = _compile(columns=[
+        contract = _compile_requirements(columns=[
             _column("amt", presentation={"kind": "amount", "currencyField": "cur", "scale": 2})])
         self.assertEqual(contract["columnPresentation"][0]["javaFollowUp"], ["setScale(2)"])
 
     def test_contract_records_the_registered_plugin_classes(self):
-        contract = _compile(columns=[
+        contract = _compile_requirements(columns=[
             _column("amt", presentation={"kind": "amount", "currencyField": "cur"})])
         self.assertEqual(contract["pluginClasses"], ["kd.kdtest.report.P"])
+        self.assertEqual(contract["pluginTypes"], {"kd.kdtest.report.P": "reportlist"})
         self.assertEqual(contract["formNumber"], "kdtest_rpt")
         self.assertEqual(contract["schemaVersion"], report_ops.REPORT_PLUGIN_CONTRACT_VERSION)
 
+    def test_a_script_plugin_is_not_listed_for_java_delivery(self):
+        """pluginClasses feeds the card gate, which looks for an archived .java file.
+
+        A KingScript or JS registration has no Java source, so listing it made the gate refuse
+        the cards for a source that can never exist.
+        """
+        contract = _compile_requirements(columns=[_column("amt")], plugins=(
+            ("kd.kdtest.report.P", "Java"), ("kd.kdtest.report.ScriptPlugin", "KingScript"),
+            ("kd.kdtest.report.JsPlugin", "JS")))
+        self.assertEqual(contract["pluginClasses"], ["kd.kdtest.report.P"])
+
+    def test_the_left_tree_plugin_is_listed_with_its_own_type(self):
+        """The left tree's class sits on ReportTreeAp.ReportPlugin, a different slot and base class.
+
+        Reading only reportPlugins left it outside the card gate, and a gate message saying
+        reportlist would have sent its delivery to the wrong base class.
+        """
+        contract = report_ops.compile_report_plugin_contract({
+            "reportColumns": [_column("amt")],
+            "reportPlugins": [{"className": "kd.kdtest.report.CostReportPlugin", "type": "Java"}],
+            "reportProperties": {"tree": {"ReportPlugin": "kd.kdtest.report.CostTreePlugin"}},
+        }, "kdtest_rpt")
+        self.assertEqual(contract["pluginClasses"],
+                         ["kd.kdtest.report.CostReportPlugin", "kd.kdtest.report.CostTreePlugin"])
+        self.assertEqual(contract["pluginTypes"], {
+            "kd.kdtest.report.CostReportPlugin": "reportlist",
+            "kd.kdtest.report.CostTreePlugin": "reporttreelist",
+        })
+
+    def test_an_unparseable_properties_section_registers_no_tree_class(self):
+        types = report_ops.registered_report_plugin_types({
+            "reportPlugins": [{"className": "kd.kdtest.report.P"}],
+            "reportProperties": ["not", "an", "object"],
+        })
+        self.assertEqual(types, {"kd.kdtest.report.P": "reportlist"})
+
 
 class WriteReportPluginContractTest(unittest.TestCase):
     """Persisting is how Java delivery picks the contract up."""
 
     def test_contract_is_written_next_to_the_run_result(self):
-        contract = _compile(columns=[
+        contract = _compile_requirements(columns=[
             _column("amt", presentation={"kind": "amount", "currencyField": "cur"})])
         with tempfile.TemporaryDirectory() as tmp:
             path = report_ops.write_report_plugin_contract(tmp, "kdtest_rpt", contract)
@@ -416,5 +601,297 @@ class WriteReportPluginContractTest(unittest.TestCase):
             self.assertFalse(os.path.isdir(os.path.join(tmp, "_runtime")))
 
 
+class IncrementalReportAuthoringTest(unittest.TestCase):
+    def baseline(self, root):
+        artifact = {'reportColumns': [_column('amt', presentation={'kind': 'decimal', 'scale': 3})],
+            'reportFilters': [{'fieldPath': 'flt_period', 'displayName': 'Period', 'compare': '=', 'mustInput': True},
+                              {'fieldPath': 'flt_person', 'displayName': 'Person', 'compare': '='}],
+            'reportPlugins': [{'className': 'kd.sample.report.Query', 'type': 'Java'}]}
+        schema = {'readBackAvailable': True, 'readBackSource': 'canonical',
+                  'reportColumns': artifact['reportColumns'], 'reportFilters': report_ops._build_filters_payload(artifact['reportFilters'])}
+        report_ops.write_report_authoring_state(root, 'sample_rpt', 'FORM', artifact, schema)
+        return artifact, schema
+
+    def test_append_keeps_old_presentation_and_adds_basedata_contract(self):
+        with tempfile.TemporaryDirectory() as root:
+            artifact, before = self.baseline(root)
+            person = _column('person_id', 'bigint', {'kind': 'basedata', 'entityId': 'bos_user', 'displayProp': 'name'})
+            after = {**before, 'reportColumns': [*artifact['reportColumns'], person]}
+            # 已有同键列被平台跳过，请求的 scale=8 不能覆盖原有 scale=3。
+            requested = [_column('amt', presentation={'kind': 'decimal', 'scale': 8}), person]
+            result = report_ops.sync_report_authoring_state(root, 'sample_rpt', 'FORM', 'columnsAppend',
+                {'before': before['reportColumns'], 'requested': requested}, before, after, {'verified': True})
+            with open(result['contractPath'], encoding='utf-8') as handle:
+                contract = json.load(handle)
+            self.assertEqual(contract['dataSetColumns'], ['amt', 'person_id'])
+            self.assertEqual(contract['columnPresentation'][0]['scale'], 3)
+            self.assertEqual(contract['columnPresentation'][1]['entityId'], 'bos_user')
+            again = report_ops.sync_report_authoring_state(root, 'sample_rpt', 'FORM', 'columnsAppend',
+                {'before': after['reportColumns'], 'requested': requested}, after, after, {'verified': True})
+            with open(again['artifactPath'], encoding='utf-8') as handle:
+                self.assertEqual(len(json.load(handle)['reportColumns']), 2)
+
+    def test_filter_replacement_removes_withdrawn_requirement_and_preserves_columns(self):
+        with tempfile.TemporaryDirectory() as root:
+            artifact, before = self.baseline(root)
+            filters = artifact['reportFilters'][:1]
+            after = {**before, 'reportFilters': filters}
+            result = report_ops.sync_report_authoring_state(root, 'sample_rpt', 'FORM', 'filters',
+                filters, before, after, {'verified': True})
+            with open(result['contractPath'], encoding='utf-8') as handle:
+                contract = json.load(handle)
+            self.assertEqual([row['filterKey'] for row in contract['filterValueContracts']], ['flt_period'])
+            self.assertEqual(contract['dataSetColumns'], ['amt'])
+            self.assertEqual(contract['columnPresentation'][0]['scale'], 3)
+
+    def test_missing_baseline_readback_failure_and_designer_drift_fail_closed(self):
+        for mode in ('missing', 'unverified', 'drift', 'identity'):
+            with self.subTest(mode=mode), tempfile.TemporaryDirectory() as root:
+                artifact, before = self.baseline(root) if mode != 'missing' else ({}, {})
+                if mode == 'drift':
+                    before = {**before, 'reportColumns': [_column('unknown')]}
+                result = report_ops.sync_report_authoring_state(root, 'sample_rpt', 'OTHER' if mode == 'identity' else 'FORM',
+                    'filters', [], before, {**before, 'reportFilters': []}, {'verified': mode != 'unverified'})
+                self.assertEqual(result['status'], 'incomplete')
+                self.assertTrue(result['platformMutationApplied'])
+                with open(result['path'], encoding='utf-8') as handle:
+                    self.assertEqual(json.load(handle)['status'], 'incomplete')
+
+    def test_write_receipt_survives_failed_readback_without_replaying_mutation(self):
+        import cosmic_api
+        from unittest import mock
+        with tempfile.TemporaryDirectory() as root:
+            artifact, before = self.baseline(root)
+            with mock.patch.object(cosmic_api, 'do_get_report_schema', side_effect=OSError('gateway unavailable')) as read:
+                result = cosmic_api._attach_report_readback({}, 'fixture', 'FORM', 'filters',
+                    artifact['reportFilters'][:1], {'formNumber': 'sample_rpt', 'formId': 'FORM'},
+                    app_root=root, schema_before=before)
+            read.assert_called_once()
+            self.assertTrue(result['status'])
+            self.assertTrue(result['data']['platformMutationApplied'])
+            self.assertFalse(result['verification']['verified'])
+            self.assertEqual(result['data']['reportAuthoringState']['status'], 'incomplete')
+
+    def test_cli_readback_refreshes_contract_using_real_verifier(self):
+        import cosmic_api
+        from unittest import mock
+        with tempfile.TemporaryDirectory() as root:
+            artifact, before = self.baseline(root)
+            filters = artifact['reportFilters'][:1]
+            after = {**before, 'reportFilters': report_ops._build_filters_payload(filters)}
+            with mock.patch.object(cosmic_api, 'do_get_report_schema', return_value=after):
+                result = cosmic_api._attach_report_readback({}, 'fixture', 'FORM', 'filters', filters,
+                    {'formNumber': 'sample_rpt', 'formId': 'FORM'}, app_root=root, schema_before=before)
+            self.assertTrue(result['verification']['verified'])
+            self.assertEqual(result['data']['reportAuthoringState']['status'], 'current')
+
+    def test_scoped_serve_mutation_invalidates_old_contract_but_dry_run_does_not(self):
+        import cosmic_api
+        from unittest import mock
+        with tempfile.TemporaryDirectory() as root:
+            artifact, before = self.baseline(root)
+            path = report_ops.report_authoring_path(root, 'sample_rpt')
+            args = {'appRoot': root, 'formNumber': 'sample_rpt', 'plugin': {'className': 'kd.sample.report.New'}}
+            with mock.patch.object(cosmic_api, 'do_register_report_plugin', return_value='kd.sample.report.New'):
+                cosmic_api._dispatch_serve({}, 'fixture', 'registerReportPlugin', {**args, 'dryRun': True})
+                self.assertEqual(json.loads(path.read_text())['status'], 'current')
+                cosmic_api._dispatch_serve({}, 'fixture', 'registerReportPlugin', args)
+                self.assertEqual(json.loads(path.read_text())['status'], 'incomplete')
+
+    def test_property_writes_invalidate_only_successful_unmerged_baseline(self):
+        import cosmic_api
+        with tempfile.TemporaryDirectory() as root:
+            artifact, before = self.baseline(root)
+            path = report_ops.report_authoring_path(root, 'sample_rpt')
+            cosmic_api._invalidate_unmerged_report_state({'status': False}, 'setReportFilterFieldConfig', root, 'sample_rpt')
+            self.assertEqual(json.loads(path.read_text())['status'], 'current')
+            result = cosmic_api._invalidate_unmerged_report_state({'status': True, 'data': {}},
+                'setReportFilterFieldConfig', root, 'sample_rpt')
+            self.assertEqual(result['data']['reportAuthoringState']['status'], 'incomplete')
+            self.assertEqual(json.loads(path.read_text())['status'], 'incomplete')
+
+    def test_scoped_failed_writes_distinguish_uncertain_from_applied(self):
+        import cosmic_api
+        from unittest import mock
+        for mode in ('rejected', 'transport', 'readback', 'mismatch'):
+            with self.subTest(mode=mode), tempfile.TemporaryDirectory() as root:
+                self.baseline(root)
+                response = {'status': False, 'message': 'save rejected'} if mode == 'rejected' else {'status': True}
+                observed = {'ReportFilterFieldConfig': {'reportFilterFields': [{'key': 'other'}]}}
+                with mock.patch.object(report_ops, '_api_call', return_value=response,
+                        side_effect=TimeoutError('gateway') if mode == 'transport' else None) as write, \
+                        mock.patch.object(report_ops, 'read_report_element_properties', return_value=observed,
+                        side_effect=OSError('gateway') if mode == 'readback' else None) as read:
+                    result = cosmic_api._dispatch_serve({}, 'fixture', 'setReportFilterFieldConfig',
+                        {'appRoot': root, 'formNumber': 'sample_rpt', 'fields': [{'key': 'flt_period'}]})
+                write.assert_called_once()
+                self.assertFalse(result['status'])
+                self.assertFalse(cosmic_api._serve_result_success(result))
+                state = json.loads(report_ops.report_authoring_path(root, 'sample_rpt').read_text())
+                self.assertEqual(state['status'], 'incomplete')
+                evidence = 'platformMutationApplied' if mode in ('readback', 'mismatch') else 'platformMutationPossible'
+                absent = 'platformMutationPossible' if evidence == 'platformMutationApplied' else 'platformMutationApplied'
+                self.assertTrue(state[evidence])
+                self.assertNotIn(absent, state)
+                self.assertTrue(result['data'][evidence])
+                self.assertFalse(result['data']['runtimeVerified'])
+                self.assertEqual(read.call_count, int(mode in ('readback', 'mismatch')))
+
+    def test_preflight_dry_run_and_unscoped_failure_do_not_invalidate_other_baselines(self):
+        import cosmic_api
+        from unittest import mock
+        with tempfile.TemporaryDirectory() as root:
+            self.baseline(root)
+            args = {'appRoot': root, 'formNumber': 'sample_rpt', 'fields': [{'key': 'flt_period'}]}
+            path = report_ops.report_authoring_path(root, 'sample_rpt')
+            with mock.patch.object(report_ops, '_api_call', side_effect=TimeoutError('gateway')) as write:
+                with self.assertRaises(ValueError):
+                    cosmic_api._dispatch_serve({}, 'fixture', 'setReportFilterFieldConfig', {**args, 'fields': []})
+                cosmic_api._dispatch_serve({}, 'fixture', 'setReportFilterFieldConfig', {**args, 'dryRun': True})
+                write.assert_not_called()
+                self.assertEqual(json.loads(path.read_text())['status'], 'current')
+                unscoped = {key: value for key, value in args.items() if key != 'appRoot'}
+                result = cosmic_api._dispatch_serve({}, 'fixture', 'setReportFilterFieldConfig', unscoped)
+                write.assert_called_once()
+                self.assertFalse(result['status'])
+                self.assertNotIn('reportAuthoringState', result['data'])
+                self.assertEqual(json.loads(path.read_text())['status'], 'current')
+
+    def test_cli_failure_keeps_report_state_evidence_and_restores_stdout(self):
+        import builtins
+        import cosmic_api
+        import io
+        from contextlib import redirect_stdout, redirect_stderr
+        from types import SimpleNamespace
+        from unittest import mock
+        for applied in (None, True):
+            with self.subTest(applied=applied), tempfile.TemporaryDirectory() as root:
+                self.baseline(root)
+                original_print = builtins.print
+                output, errors = io.StringIO(), io.StringIO()
+                def execute():
+                    cosmic_api._CLI_DELIVERY_ARGS = SimpleNamespace(
+                        cmd='setReportFilterFieldConfig', app_root=root, formNumber='sample_rpt', dry_run=False)
+                    raise report_ops.ReportMutationError('REPORT_WRITE_OUTCOME_UNKNOWN: fixture', applied)
+                with mock.patch.object(cosmic_api, '_main_impl', side_effect=execute), \
+                        mock.patch.object(sys, 'argv', ['cosmic_api.py', '--stdout']), \
+                        redirect_stdout(output), redirect_stderr(errors):
+                    self.assertEqual(cosmic_api.main(), 1)
+                    self.assertIs(builtins.print, original_print)
+                    print('CARD_STDOUT_RESTORED')
+                lines = output.getvalue().splitlines()
+                result = json.loads('\n'.join(lines[:-1]))
+                self.assertEqual(lines[-1], 'CARD_STDOUT_RESTORED')
+                self.assertFalse(result['status'])
+                self.assertEqual(result['data']['reportAuthoringState']['status'], 'incomplete')
+                self.assertTrue(result['data']['platformMutationApplied' if applied else 'platformMutationPossible'])
+
+    def test_cli_success_restores_print_and_output_context_for_following_cards(self):
+        import builtins
+        import cosmic_api
+        import io
+        from _core import formatters
+        from contextlib import redirect_stdout, redirect_stderr
+        from unittest import mock
+        original_print = builtins.print
+        previous = (formatters._stdout_mode, formatters._output_file,
+                    formatters._current_cmd, formatters._current_arg_hash)
+        output, errors = io.StringIO(), io.StringIO()
+        with mock.patch.object(sys, 'argv', ['cosmic_api.py', '--stdout', 'describeCommand', 'setReportFilters']), \
+                redirect_stdout(output), redirect_stderr(errors):
+            self.assertEqual(cosmic_api.main(), 0)
+            self.assertIs(builtins.print, original_print)
+            self.assertEqual((formatters._stdout_mode, formatters._output_file,
+                             formatters._current_cmd, formatters._current_arg_hash), previous)
+            print('CARD_STDOUT_RESTORED')
+        lines = output.getvalue().splitlines()
+        self.assertEqual(lines[-1], 'CARD_STDOUT_RESTORED')
+        self.assertEqual(json.loads('\n'.join(lines[:-1]))['action']['command'], 'setReportFilters')
+
+    def test_internal_executor_does_not_install_a_process_wide_print_router(self):
+        import builtins
+        import cosmic_api
+        from _core import formatters
+        from unittest import mock
+        original_print = builtins.print
+        with mock.patch.object(sys, 'argv', ['cosmic_api.py', '--stdout', 'auth']), \
+                mock.patch.object(builtins, 'print', original_print), \
+                mock.patch.object(formatters, '_stdout_mode', False), \
+                mock.patch.object(cosmic_api, '_CLI_MACHINE_MODE', False), \
+                mock.patch.object(cosmic_api, '_CLI_DELIVERY_ARGS', None), \
+                mock.patch.object(cosmic_api, '_resolve_app_root_arg', side_effect=RuntimeError('fixture-stop')):
+            with self.assertRaisesRegex(RuntimeError, 'fixture-stop'):
+                cosmic_api._main_impl()
+            self.assertIs(builtins.print, original_print)
+
+    def test_unexpected_write_response_and_rejected_save_are_not_preflight_failures(self):
+        for response in (None, [], {'status': False}, {'errorCode': 'SAVE_REJECTED'}, {'data': {'success': False}}):
+            with self.subTest(response=response):
+                with self.assertRaises(report_ops.ReportMutationError) as failure:
+                    report_ops._check_result(response, 'setReportFilters', form_mutation_possible=True)
+                self.assertIsNone(failure.exception.mutation_applied)
+                self.assertIn('do not repeat the same write blindly', str(failure.exception))
+        with self.assertRaises(RuntimeError) as failure:
+            report_ops._check_result({'status': False}, 'getFormSchema')
+        self.assertNotIsInstance(failure.exception, report_ops.ReportMutationError)
+
+    def test_malformed_readback_preserves_successful_write_and_invalidates_state(self):
+        import cosmic_api
+        from unittest import mock
+        for schema in (None, [], {'readBackAvailable': True, 'reportFilters': [None]}):
+            with self.subTest(schema=schema), tempfile.TemporaryDirectory() as root:
+                artifact, before = self.baseline(root)
+                with mock.patch.object(cosmic_api, 'do_get_report_schema', return_value=schema):
+                    result = cosmic_api._attach_report_readback({}, 'fixture', 'FORM', 'filters',
+                        artifact['reportFilters'][:1], {'formNumber': 'sample_rpt', 'formId': 'FORM'},
+                        app_root=root, schema_before=before)
+                self.assertTrue(result['data']['platformMutationApplied'])
+                self.assertFalse(result['verification']['verified'])
+                self.assertEqual(json.loads(report_ops.report_authoring_path(root, 'sample_rpt').read_text())['status'], 'incomplete')
+
+    def test_design_state_mismatch_preserves_successful_property_write(self):
+        import cosmic_api
+        from unittest import mock
+        result = {'designStateExpectation': {'hostType': 'ReportListAp', 'expected': {'MaxRowHeight': 32}}}
+        with mock.patch.object(cosmic_api, '_export_report_dym_evidence', return_value='fixture.dym'), \
+                mock.patch.object(cosmic_api, 'attach_report_property_design_state',
+                    side_effect=RuntimeError('REPORT_PROPERTY_MISMATCH: fixture')):
+            with self.assertRaises(report_ops.ReportMutationError) as failure:
+                cosmic_api._settle_report_property_design_state({}, 'fixture', result, 'sample_rpt', 'app', 'setReportProperties')
+        self.assertTrue(failure.exception.mutation_applied)
+        self.assertTrue(cosmic_api._report_mutation_failure(failure.exception)['data']['platformMutationApplied'])
+
+    def test_atomic_local_save_failure_cleans_only_its_temporary_files(self):
+        from pathlib import Path
+        from unittest import mock
+        with tempfile.TemporaryDirectory() as root:
+            artifact, schema = self.baseline(root)
+            runtime = Path(root) / '_runtime'
+            unrelated = runtime / 'unrelated.tmp'
+            unrelated.write_text('keep')
+            with mock.patch.object(report_ops.os, 'replace', side_effect=OSError('save failed')):
+                with self.assertRaises(OSError):
+                    report_ops.write_report_authoring_state(root, 'sample_rpt', 'FORM', artifact, schema)
+            self.assertEqual(list(runtime.glob('*.tmp')), [unrelated])
+            self.assertEqual(json.loads(report_ops.report_authoring_path(root, 'sample_rpt').read_text())['status'], 'incomplete')
+
+    def test_contract_compile_failure_leaves_state_incomplete(self):
+        from unittest import mock
+        with tempfile.TemporaryDirectory() as root:
+            artifact, before = self.baseline(root)
+            with mock.patch.object(report_ops, 'compile_report_plugin_contract', side_effect=ValueError('invalid contract')):
+                with self.assertRaises(ValueError):
+                    report_ops.write_report_authoring_state(root, 'sample_rpt', 'FORM', artifact, before)
+            self.assertEqual(json.loads(report_ops.report_authoring_path(root, 'sample_rpt').read_text())['status'], 'incomplete')
+
+    def test_query_data_source_only_does_not_create_a_java_contract(self):
+        with tempfile.TemporaryDirectory() as root:
+            artifact = {'queryDataSource': {'number': 'sample_data'}, 'reportColumns': [_column('amt')]}
+            result = report_ops.write_report_authoring_state(root, 'sample_rpt', 'FORM', artifact,
+                {'reportColumns': artifact['reportColumns']})
+            self.assertEqual(result['contractPath'], '')
+            self.assertFalse(os.path.isfile(os.path.join(root, '_runtime', 'sample_rpt.report-plugin-contract.json')))
+
+
 if __name__ == "__main__":
     unittest.main()