direct: Include precise reason in the plan (#4448)

denik · web-flow · commit 895730daa459 · 2026-02-05T15:54:40.000Z
## Changes
Instead of marking all fields from the config as "builtin_rule", specify
which field behaviour this decision is based on, e.g. "spec:output_only"
or "spec:immutable". For manual reasons, there is "spec:" prefix.

## Why
Seeing "builtin_rule" in the plan does not tell enough about this field.

## Tests
Existing tests where plan is recorded.
diff --git a/acceptance/bundle/migrate/dashboards/out.plan_after_migrate.json b/acceptance/bundle/migrate/dashboards/out.plan_after_migrate.json
@@ -29,7 +29,7 @@
         },
         "serialized_dashboard": {
           "action": "skip",
-          "reason": "builtin_rule",
+          "reason": "etag_based",
           "old": "{\"pages\":[{\"name\":\"02724bf2\",\"displayName\":\"Dashboard test bundle-deploy-dashboard\"}]}\n",
           "new": "{\"pages\":[{\"name\":\"02724bf2\",\"displayName\":\"Dashboard test bundle-deploy-dashboard\"}]}\n",
           "remote": "{\"pages\":[{\"displayName\":\"Dashboard test bundle-deploy-dashboard\",\"name\":\"02724bf2\",\"pageType\":\"PAGE_TYPE_CANVAS\"}]}\n"
diff --git a/acceptance/bundle/migrate/runas/out.plan.json b/acceptance/bundle/migrate/runas/out.plan.json
@@ -37,7 +37,7 @@
       "changes": {
         "run_as": {
           "action": "skip",
-          "reason": "builtin_rule",
+          "reason": "not_returned_by_api",
           "old": {
             "service_principal_name": "[UUID]"
           },
diff --git a/acceptance/bundle/resource_deps/pipelines_recreate/out.plan_update.direct.json b/acceptance/bundle/resource_deps/pipelines_recreate/out.plan_update.direct.json
@@ -114,7 +114,7 @@
       "changes": {
         "storage": {
           "action": "recreate",
-          "reason": "builtin_rule",
+          "reason": "immutable",
           "old": "dbfs:/my-storage",
           "new": "dbfs:/my-new-storage",
           "remote": "dbfs:/my-storage"
diff --git a/acceptance/bundle/resources/dashboards/dataset-catalog-schema/out.plan.direct.json b/acceptance/bundle/resources/dashboards/dataset-catalog-schema/out.plan.direct.json
@@ -23,13 +23,13 @@
       "changes": {
         "dataset_catalog": {
           "action": "skip",
-          "reason": "builtin_rule",
+          "reason": "input_only",
           "old": "main",
           "new": "main"
         },
         "dataset_schema": {
           "action": "skip",
-          "reason": "builtin_rule",
+          "reason": "input_only",
           "old": "default",
           "new": "default"
         },
diff --git a/acceptance/bundle/resources/dashboards/detect-change/out.plan.direct.json b/acceptance/bundle/resources/dashboards/detect-change/out.plan.direct.json
@@ -38,7 +38,7 @@
         },
         "serialized_dashboard": {
           "action": "skip",
-          "reason": "builtin_rule",
+          "reason": "etag_based",
           "old": "{\n  \"pages\": [\n    {\n      \"displayName\": \"New Page\",\n      \"layout\": [\n        {\n          \"position\": {\n            \"height\": 2,\n            \"width\": 6,\n            \"x\": 0,\n            \"y\": 0\n          },\n          \"widget\": {\n            \"name\": \"82eb9107\",\n            \"textbox_spec\": \"# I'm a title\"\n          }\n        },\n        {\n          \"position\": {\n            \"height\": 2,\n            \"width\": 6,\n            \"x\": 0,\n            \"y\": 2\n          },\n          \"widget\": {\n            \"name\": \"ffa6de4f\",\n            \"textbox_spec\": \"Text\"\n          }\n        }\n      ],\n      \"name\": \"fdd21a3c\"\n    }\n  ]\n}\n",
           "new": "{\n  \"pages\": [\n    {\n      \"displayName\": \"New Page\",\n      \"layout\": [\n        {\n          \"position\": {\n            \"height\": 2,\n            \"width\": 6,\n            \"x\": 0,\n            \"y\": 0\n          },\n          \"widget\": {\n            \"name\": \"82eb9107\",\n            \"textbox_spec\": \"# I'm a title\"\n          }\n        },\n        {\n          \"position\": {\n            \"height\": 2,\n            \"width\": 6,\n            \"x\": 0,\n            \"y\": 2\n          },\n          \"widget\": {\n            \"name\": \"ffa6de4f\",\n            \"textbox_spec\": \"Text\"\n          }\n        }\n      ],\n      \"name\": \"fdd21a3c\"\n    }\n  ]\n}\n",
           "remote": "{}\n"
diff --git a/acceptance/bundle/resources/dashboards/simple/out.plan.direct.json b/acceptance/bundle/resources/dashboards/simple/out.plan.direct.json
@@ -29,7 +29,7 @@
         },
         "serialized_dashboard": {
           "action": "skip",
-          "reason": "builtin_rule",
+          "reason": "etag_based",
           "old": "{ }\n",
           "new": "{ }\n",
           "remote": "{}\n"
diff --git a/acceptance/bundle/resources/dashboards/unpublish-out-of-band/out.plan.direct.json b/acceptance/bundle/resources/dashboards/unpublish-out-of-band/out.plan.direct.json
@@ -45,7 +45,7 @@
         },
         "serialized_dashboard": {
           "action": "skip",
-          "reason": "builtin_rule",
+          "reason": "etag_based",
           "old": "{\"pages\":[{\"displayName\":\"Test Dashboard\",\"name\":\"test-page\"}]}",
           "new": "{\"pages\":[{\"displayName\":\"Test Dashboard\",\"name\":\"test-page\"}]}",
           "remote": "{\"pages\":[{\"displayName\":\"Test Dashboard\",\"name\":\"test-page\",\"pageType\":\"PAGE_TYPE_CANVAS\"}]}"
diff --git a/acceptance/bundle/resources/model_serving_endpoints/basic/out.second-plan.direct.json b/acceptance/bundle/resources/model_serving_endpoints/basic/out.second-plan.direct.json
@@ -36,7 +36,7 @@
         },
         "name": {
           "action": "recreate",
-          "reason": "builtin_rule",
+          "reason": "immutable",
           "old": "[ENDPOINT_NAME_1]",
           "new": "[ENDPOINT_NAME_2]",
           "remote": "[ENDPOINT_NAME_1]"
diff --git a/acceptance/bundle/resources/model_serving_endpoints/recreate/catalog-name/out.second-plan.direct.json b/acceptance/bundle/resources/model_serving_endpoints/recreate/catalog-name/out.second-plan.direct.json
@@ -68,7 +68,7 @@
       "changes": {
         "config.auto_capture_config.catalog_name": {
           "action": "recreate",
-          "reason": "builtin_rule",
+          "reason": "immutable",
           "old": "main",
           "new": "other_catalog",
           "remote": "main"
diff --git a/acceptance/bundle/resources/model_serving_endpoints/recreate/name-change/out.second-plan.direct.json b/acceptance/bundle/resources/model_serving_endpoints/recreate/name-change/out.second-plan.direct.json
@@ -58,7 +58,7 @@
       "changes": {
         "name": {
           "action": "recreate",
-          "reason": "builtin_rule",
+          "reason": "immutable",
           "old": "[ORIGINAL_ENDPOINT_ID]",
           "new": "[NEW_ENDPOINT_ID]",
           "remote": "[ORIGINAL_ENDPOINT_ID]"
diff --git a/acceptance/bundle/resources/model_serving_endpoints/recreate/route-optimized/out.second-plan.direct.json b/acceptance/bundle/resources/model_serving_endpoints/recreate/route-optimized/out.second-plan.direct.json
@@ -51,7 +51,7 @@
       "changes": {
         "route_optimized": {
           "action": "recreate",
-          "reason": "builtin_rule",
+          "reason": "immutable",
           "old": false,
           "new": true,
           "remote": false
diff --git a/acceptance/bundle/resources/model_serving_endpoints/recreate/schema-name/out.second-plan.direct.json b/acceptance/bundle/resources/model_serving_endpoints/recreate/schema-name/out.second-plan.direct.json
@@ -68,7 +68,7 @@
       "changes": {
         "config.auto_capture_config.schema_name": {
           "action": "recreate",
-          "reason": "builtin_rule",
+          "reason": "immutable",
           "old": "default",
           "new": "other_schema",
           "remote": "default"
diff --git a/acceptance/bundle/resources/model_serving_endpoints/recreate/table-prefix/out.second-plan.direct.json b/acceptance/bundle/resources/model_serving_endpoints/recreate/table-prefix/out.second-plan.direct.json
@@ -68,7 +68,7 @@
       "changes": {
         "config.auto_capture_config.table_name_prefix": {
           "action": "recreate",
-          "reason": "builtin_rule",
+          "reason": "immutable",
           "old": "my_table",
           "new": "other_table",
           "remote": "my_table"
diff --git a/acceptance/bundle/resources/pipelines/recreate-keys/change-ingestion-definition/out.plan_recreate.direct.json b/acceptance/bundle/resources/pipelines/recreate-keys/change-ingestion-definition/out.plan_recreate.direct.json
@@ -65,7 +65,7 @@
       "changes": {
         "ingestion_definition.connection_name": {
           "action": "recreate",
-          "reason": "builtin_rule",
+          "reason": "immutable",
           "old": "my_connection",
           "new": "my_new_connection",
           "remote": "my_connection"
diff --git a/acceptance/bundle/resources/pipelines/recreate-keys/change-storage/out.plan_recreate.direct.json b/acceptance/bundle/resources/pipelines/recreate-keys/change-storage/out.plan_recreate.direct.json
@@ -54,7 +54,7 @@
       "changes": {
         "storage": {
           "action": "recreate",
-          "reason": "builtin_rule",
+          "reason": "immutable",
           "old": "dbfs:/pipelines/custom",
           "new": "dbfs:/pipelines/newcustom",
           "remote": "dbfs:/pipelines/custom"
diff --git a/acceptance/bundle/resources/postgres_branches/update_protected/out.plan.no_change.direct.json b/acceptance/bundle/resources/postgres_branches/update_protected/out.plan.no_change.direct.json
@@ -25,13 +25,13 @@
   "changes": {
     "is_protected": {
       "action": "skip",
-      "reason": "api_schema",
+      "reason": "spec:input_only",
       "old": false,
       "new": false
     },
     "no_expiry": {
       "action": "skip",
-      "reason": "api_schema",
+      "reason": "spec:input_only",
       "old": true,
       "new": true
     }
diff --git a/acceptance/bundle/resources/postgres_branches/update_protected/out.plan.restore.direct.json b/acceptance/bundle/resources/postgres_branches/update_protected/out.plan.restore.direct.json
@@ -38,7 +38,7 @@
     },
     "no_expiry": {
       "action": "skip",
-      "reason": "api_schema",
+      "reason": "spec:input_only",
       "old": true,
       "new": true
     }
diff --git a/acceptance/bundle/resources/postgres_branches/update_protected/out.plan.update.direct.json b/acceptance/bundle/resources/postgres_branches/update_protected/out.plan.update.direct.json
@@ -38,7 +38,7 @@
     },
     "no_expiry": {
       "action": "skip",
-      "reason": "api_schema",
+      "reason": "spec:input_only",
       "old": true,
       "new": true
     }
diff --git a/acceptance/bundle/resources/postgres_endpoints/update_autoscaling/out.plan.no_change.direct.json b/acceptance/bundle/resources/postgres_endpoints/update_autoscaling/out.plan.no_change.direct.json
@@ -28,19 +28,19 @@
   "changes": {
     "autoscaling_limit_max_cu": {
       "action": "skip",
-      "reason": "api_schema",
+      "reason": "spec:input_only",
       "old": 8,
       "new": 8
     },
     "autoscaling_limit_min_cu": {
       "action": "skip",
-      "reason": "api_schema",
+      "reason": "spec:input_only",
       "old": 0.5,
       "new": 0.5
     },
     "endpoint_type": {
       "action": "skip",
-      "reason": "api_schema",
+      "reason": "spec:input_only",
       "old": "ENDPOINT_TYPE_READ_WRITE",
       "new": "ENDPOINT_TYPE_READ_WRITE",
       "remote": ""
diff --git a/acceptance/bundle/resources/postgres_endpoints/update_autoscaling/out.plan.restore.direct.json b/acceptance/bundle/resources/postgres_endpoints/update_autoscaling/out.plan.restore.direct.json
@@ -43,13 +43,13 @@
     },
     "autoscaling_limit_min_cu": {
       "action": "skip",
-      "reason": "api_schema",
+      "reason": "spec:input_only",
       "old": 0.5,
       "new": 0.5
     },
     "endpoint_type": {
       "action": "skip",
-      "reason": "api_schema",
+      "reason": "spec:input_only",
       "old": "ENDPOINT_TYPE_READ_WRITE",
       "new": "ENDPOINT_TYPE_READ_WRITE",
       "remote": ""
diff --git a/acceptance/bundle/resources/postgres_endpoints/update_autoscaling/out.plan.update.direct.json b/acceptance/bundle/resources/postgres_endpoints/update_autoscaling/out.plan.update.direct.json
@@ -43,13 +43,13 @@
     },
     "autoscaling_limit_min_cu": {
       "action": "skip",
-      "reason": "api_schema",
+      "reason": "spec:input_only",
       "old": 0.5,
       "new": 0.5
     },
     "endpoint_type": {
       "action": "skip",
-      "reason": "api_schema",
+      "reason": "spec:input_only",
       "old": "ENDPOINT_TYPE_READ_WRITE",
       "new": "ENDPOINT_TYPE_READ_WRITE",
       "remote": ""
diff --git a/acceptance/bundle/resources/postgres_projects/update_display_name/out.plan.no_change.direct.json b/acceptance/bundle/resources/postgres_projects/update_display_name/out.plan.no_change.direct.json
@@ -22,7 +22,7 @@
   "changes": {
     "default_endpoint_settings": {
       "action": "skip",
-      "reason": "api_schema",
+      "reason": "spec:input_only",
       "old": {
         "autoscaling_limit_max_cu": 4,
         "autoscaling_limit_min_cu": 0.5,
@@ -36,7 +36,7 @@
     },
     "display_name": {
       "action": "skip",
-      "reason": "api_schema",
+      "reason": "spec:input_only",
       "old": "Original Name",
       "new": "Original Name"
     },
@@ -48,7 +48,7 @@
     },
     "pg_version": {
       "action": "skip",
-      "reason": "api_schema",
+      "reason": "spec:input_only",
       "old": 16,
       "new": 16
     }
diff --git a/acceptance/bundle/resources/postgres_projects/update_display_name/out.plan.restore.direct.json b/acceptance/bundle/resources/postgres_projects/update_display_name/out.plan.restore.direct.json
@@ -35,7 +35,7 @@
   "changes": {
     "default_endpoint_settings": {
       "action": "skip",
-      "reason": "api_schema",
+      "reason": "spec:input_only",
       "old": {
         "autoscaling_limit_max_cu": 4,
         "autoscaling_limit_min_cu": 0.5,
@@ -60,7 +60,7 @@
     },
     "pg_version": {
       "action": "skip",
-      "reason": "api_schema",
+      "reason": "spec:input_only",
       "old": 16,
       "new": 16
     }
diff --git a/acceptance/bundle/resources/postgres_projects/update_display_name/out.plan.update.direct.json b/acceptance/bundle/resources/postgres_projects/update_display_name/out.plan.update.direct.json
@@ -35,7 +35,7 @@
   "changes": {
     "default_endpoint_settings": {
       "action": "skip",
-      "reason": "api_schema",
+      "reason": "spec:input_only",
       "old": {
         "autoscaling_limit_max_cu": 4,
         "autoscaling_limit_min_cu": 0.5,
@@ -60,7 +60,7 @@
     },
     "pg_version": {
       "action": "skip",
-      "reason": "api_schema",
+      "reason": "spec:input_only",
       "old": 16,
       "new": 16
     }
diff --git a/acceptance/bundle/resources/quality_monitors/change_assets_dir/out.plan.direct.json b/acceptance/bundle/resources/quality_monitors/change_assets_dir/out.plan.direct.json
@@ -31,14 +31,14 @@
       "changes": {
         "assets_dir": {
           "action": "recreate",
-          "reason": "builtin_rule",
+          "reason": "immutable",
           "old": "/Workspace/Users/[USERNAME]/monitor_assets_[UNIQUE_NAME]",
           "new": "/Workspace/Users/[USERNAME]/monitor_assets2_[UNIQUE_NAME]",
           "remote": "/Workspace/Users/[USERNAME]/monitor_assets_[UNIQUE_NAME]"
         },
         "warehouse_id": {
           "action": "skip",
-          "reason": "builtin_rule",
+          "reason": "not_returned_by_api",
           "old": "[TEST_DEFAULT_WAREHOUSE_ID]",
           "new": "[TEST_DEFAULT_WAREHOUSE_ID]"
         }
diff --git a/acceptance/bundle/resources/quality_monitors/change_output_schema_name/out.plan.direct.json b/acceptance/bundle/resources/quality_monitors/change_output_schema_name/out.plan.direct.json
@@ -35,7 +35,7 @@
         },
         "warehouse_id": {
           "action": "skip",
-          "reason": "builtin_rule",
+          "reason": "not_returned_by_api",
           "old": "[TEST_DEFAULT_WAREHOUSE_ID]",
           "new": "[TEST_DEFAULT_WAREHOUSE_ID]"
         }
diff --git a/acceptance/bundle/resources/quality_monitors/change_table_name/out.plan.direct.json b/acceptance/bundle/resources/quality_monitors/change_table_name/out.plan.direct.json
@@ -31,14 +31,14 @@
       "changes": {
         "table_name": {
           "action": "recreate",
-          "reason": "builtin_rule",
+          "reason": "immutable",
           "old": "main.qm_test_[UNIQUE_NAME].test_table",
           "new": "main.qm_test_[UNIQUE_NAME].test_table_2",
           "remote": "main.qm_test_[UNIQUE_NAME].test_table"
         },
         "warehouse_id": {
           "action": "skip",
-          "reason": "builtin_rule",
+          "reason": "not_returned_by_api",
           "old": "[TEST_DEFAULT_WAREHOUSE_ID]",
           "new": "[TEST_DEFAULT_WAREHOUSE_ID]"
         }
diff --git a/acceptance/bundle/resources/quality_monitors/create/out.plan_noop.direct.json b/acceptance/bundle/resources/quality_monitors/create/out.plan_noop.direct.json
@@ -20,7 +20,7 @@
       "changes": {
         "warehouse_id": {
           "action": "skip",
-          "reason": "builtin_rule",
+          "reason": "not_returned_by_api",
           "old": "[TEST_DEFAULT_WAREHOUSE_ID]",
           "new": "[TEST_DEFAULT_WAREHOUSE_ID]"
         }
diff --git a/acceptance/bundle/resources/secret_scopes/basic/out.plan2.direct.json b/acceptance/bundle/resources/secret_scopes/basic/out.plan2.direct.json
@@ -19,7 +19,7 @@
       "changes": {
         "scope": {
           "action": "recreate",
-          "reason": "builtin_rule",
+          "reason": "immutable",
           "old": "test-scope-[UNIQUE_NAME]-1",
           "new": "test-scope-[UNIQUE_NAME]-2",
           "remote": "test-scope-[UNIQUE_NAME]-1"
@@ -68,7 +68,7 @@
       "changes": {
         "scope_name": {
           "action": "update_id",
-          "reason": "builtin_rule",
+          "reason": "id_changes",
           "old": "test-scope-[UNIQUE_NAME]-1",
           "new": "",
           "remote": "test-scope-[UNIQUE_NAME]-1"
diff --git a/acceptance/bundle/resources/volumes/change-name/out.plan.direct.json b/acceptance/bundle/resources/volumes/change-name/out.plan.direct.json
@@ -32,7 +32,7 @@
       "changes": {
         "name": {
           "action": "update_id",
-          "reason": "builtin_rule",
+          "reason": "id_changes",
           "old": "myvolume",
           "new": "mynewvolume",
           "remote": "myvolume"
diff --git a/bundle/deployplan/plan.go b/bundle/deployplan/plan.go
@@ -101,8 +101,6 @@ const (
 	ReasonServerSideDefault = "server_side_default"
 	ReasonAlias             = "alias"
 	ReasonRemoteAlreadySet  = "remote_already_set"
-	ReasonBuiltinRule       = "builtin_rule"
-	ReasonAPISchema         = "api_schema"
 	ReasonEmptySlice        = "empty_slice"
 	ReasonEmptyMap          = "empty_map"
 	ReasonEmptyStruct       = "empty_struct"
diff --git a/bundle/direct/bundle_plan.go b/bundle/direct/bundle_plan.go
diff --git a/bundle/direct/dresources/adapter.go b/bundle/direct/dresources/adapter.go
diff --git a/bundle/direct/dresources/all_test.go b/bundle/direct/dresources/all_test.go
diff --git a/bundle/direct/dresources/config.go b/bundle/direct/dresources/config.go
diff --git a/bundle/direct/dresources/resources.generated.yml b/bundle/direct/dresources/resources.generated.yml
diff --git a/bundle/direct/dresources/resources.yml b/bundle/direct/dresources/resources.yml
diff --git a/bundle/direct/tools/generate_resources.py b/bundle/direct/tools/generate_resources.py
