feat(table-catalog): expose backing migration contract (#3574)

* feat(table-catalog): expose backing migration contract

* fix(table-catalog): require register auth for external sync

---------

Co-authored-by: Henry Guo <marshawcoco@users.noreply.github.com>

scripts/table-catalog/README.md

@@ -125,6 +125,7 @@ PyIceberg, PyArrow, or boto3:
 python3 scripts/table-catalog/pyiceberg_smoke.py --print-client-matrix
 python3 scripts/table-catalog/pyiceberg_smoke.py --print-vendor-profiles
 python3 scripts/table-catalog/pyiceberg_smoke.py --print-unsupported-inventory
+python3 scripts/table-catalog/pyiceberg_smoke.py --print-production-readiness
 ```
 
 Use these outputs when updating release notes, PR descriptions, or follow-up
@@ -143,6 +144,9 @@ The smoke test also probes catalog-backed advanced Iceberg surfaces:
   execution checks
 - catalog diagnostics exposes the table recovery and consistency state used by
   operators
+- catalog export and diagnostics expose the current catalog backing manifest,
+  recoverable commit-log WAL state, strong backing migration target, single
+  active writer HA policy, and scale validation matrix
 
 ## Client Matrix
 

scripts/table-catalog/pyiceberg_smoke.py

@@ -178,6 +178,24 @@ UNSUPPORTED_INVENTORY: list[dict[str, str]] = [
     },
 ]
 
+PRODUCTION_READINESS_INVENTORY: list[dict[str, str]] = [
+    {
+        "capability": "strong-catalog-backing",
+        "status": "migration-contract-supported",
+        "validation": "catalog export and diagnostics expose an object-backed manifest, recoverable commit-log WAL state, strong-kv-wal migration target, required migration steps, and recovery blockers before cutover",
+    },
+    {
+        "capability": "single-active-writer-ha",
+        "status": "policy-published",
+        "validation": "diagnostics publish single-active-writer-region semantics, linearizable leader-read requirements for commits, read-only replica limits, and explicit no active-active support",
+    },
+    {
+        "capability": "scale-validation-matrix",
+        "status": "matrix-published",
+        "validation": "required validation scenarios are machine-readable: concurrent commit CAS, commit-log recovery replay, migration snapshot replay, stale replica read guards, and long-running client conformance",
+    },
+]
+
 
 @dataclass(frozen=True)
 class RuntimeDeps:
@@ -225,6 +243,10 @@ def unsupported_inventory() -> list[dict[str, str]]:
     return [entry.copy() for entry in UNSUPPORTED_INVENTORY]
 
 
+def production_readiness_inventory() -> list[dict[str, str]]:
+    return [entry.copy() for entry in PRODUCTION_READINESS_INVENTORY]
+
+
 def normalized_rest_path(rest_path: str) -> str:
     stripped = rest_path.strip()
     if not stripped:
@@ -278,6 +300,11 @@ def parse_args() -> argparse.Namespace:
     parser.add_argument("--print-client-matrix", action="store_true", help="Print the current client conformance matrix as JSON and exit.")
     parser.add_argument("--print-vendor-profiles", action="store_true", help="Print vendor connection profile references as JSON and exit.")
     parser.add_argument("--print-unsupported-inventory", action="store_true", help="Print unsupported capability inventory as JSON and exit.")
+    parser.add_argument(
+        "--print-production-readiness",
+        action="store_true",
+        help="Print catalog backing, HA, and scale-readiness inventory as JSON and exit.",
+    )
     return apply_profile_defaults(parser.parse_args())
 
 
@@ -700,6 +727,9 @@ def printed_metadata(args: argparse.Namespace) -> bool:
     if args.print_unsupported_inventory:
         print_json_document({"unsupported_inventory": unsupported_inventory()})
         printed = True
+    if args.print_production_readiness:
+        print_json_document({"production_readiness": production_readiness_inventory()})
+        printed = True
     return printed
 
 

scripts/table-catalog/test_pyiceberg_smoke.py

@@ -753,11 +753,25 @@ class PyIcebergSmokeConfigTest(unittest.TestCase):
             self.assertIn("status", entry)
             self.assertIn("roadmap_area", entry)
 
+    def test_production_readiness_inventory_tracks_catalog_backing(self) -> None:
+        inventory = pyiceberg_smoke.production_readiness_inventory()
+        capabilities = {entry["capability"] for entry in inventory}
+
+        self.assertIn("strong-catalog-backing", capabilities)
+        self.assertIn("single-active-writer-ha", capabilities)
+        self.assertIn("scale-validation-matrix", capabilities)
+        strong_backing = next(entry for entry in inventory if entry["capability"] == "strong-catalog-backing")
+        self.assertEqual(strong_backing["status"], "migration-contract-supported")
+        for entry in inventory:
+            self.assertIn("status", entry)
+            self.assertIn("validation", entry)
+
     def test_published_table_catalog_docs_do_not_use_internal_roadmap_labels(self) -> None:
         readme = (SCRIPT_DIR / "README.md").read_text(encoding="utf-8")
 
         self.assertIsNone(INTERNAL_ROADMAP_LABEL_RE.search(readme))
         self.assertIsNone(INTERNAL_ROADMAP_LABEL_RE.search(str(pyiceberg_smoke.unsupported_inventory())))
+        self.assertIsNone(INTERNAL_ROADMAP_LABEL_RE.search(str(pyiceberg_smoke.production_readiness_inventory())))
 
 
 if __name__ == "__main__":