fix(catalog): CI lint/mypy/docstring for companion-catalog additions

- companion.py: single-line summary (D205); type-annotate table_scan_branches_get
  params (mypy no-untyped-def).
- ScanBranch docstring: order Attributes to match field order (source_* after
  writable) — DOC604/605.
- ReadOnlyCatalogInterface docstring: document attach_catalogs (DOC601/603).
- __init__: sorted AttachCatalogInfo import (I001).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: rustyconover

vgi/_test_fixtures/companion.py

@@ -1,7 +1,9 @@
 # Copyright 2025, 2026 Query Farm LLC - https://query.farm
 
-"""Test fixture: a VGI catalog that advertises a companion catalog + a
-multi-branch table whose branches are catalog-table branches on that companion.
+"""Companion-catalog (lakehouse federation) test fixture.
+
+A VGI catalog that advertises a companion catalog + a multi-branch table whose
+branches are catalog-table branches on that companion.
 
 Exercises the lakehouse-federation feature end-to-end:
 
@@ -38,12 +40,14 @@
 
 from vgi.catalog import (
     AttachCatalogInfo,
+    AttachOpaqueData,
     Catalog,
     ReadOnlyCatalogInterface,
     ScanBranch,
     ScanBranchesResult,
     Schema,
     Table,
+    TransactionOpaqueData,
 )
 from vgi.worker import Worker
 
@@ -116,8 +120,8 @@ class CompanionCatalog(ReadOnlyCatalogInterface):
     def table_scan_branches_get(
         self,
         *,
-        attach_opaque_data,  # noqa: ANN001
-        transaction_opaque_data,  # noqa: ANN001
+        attach_opaque_data: AttachOpaqueData,
+        transaction_opaque_data: TransactionOpaqueData | None,
         schema_name: str,
         name: str,
         at_unit: str | None = None,

vgi/catalog/__init__.py

@@ -7,11 +7,11 @@
 """
 
 from vgi.catalog.catalog_interface import (
+    AttachCatalogInfo,
     AttachOpaqueData,
     CatalogAttachResult,
     CatalogDataVersionRelease,
     CatalogExample,
-    AttachCatalogInfo,
     CatalogInfo,
     CatalogInterface,
     CatalogObject,

vgi/catalog/catalog_interface.py

@@ -932,14 +932,6 @@ class ScanBranch:
             table function). The C++ rewriter resolves this name against
             DuckDB's function catalog and binds it at optimize time. Empty
             string for a catalog-table branch.
-        source_catalog: Catalog-table branch only — the attached catalog name
-            (matches an :attr:`AttachCatalogInfo.alias`). ``None`` for function
-            branches.
-        source_schema: Catalog-table branch only — the schema of the source
-            table. ``None`` for function branches.
-        source_table: Catalog-table branch only — the base table name; its
-            presence selects the catalog-table kind. ``None`` for function
-            branches.
         positional_arguments: Positional arguments as PyArrow scalars,
             passed through to the function's ``bind``.
         named_arguments: Named arguments as PyArrow scalars.
@@ -960,6 +952,14 @@ class ScanBranch:
             remain refused on multi-branch tables regardless of this
             flag; the contract is INSERT-only until cross-arm
             semantics have customer-driven evidence.
+        source_catalog: Catalog-table branch only — the attached catalog name
+            (matches an :attr:`AttachCatalogInfo.alias`). ``None`` for function
+            branches.
+        source_schema: Catalog-table branch only — the schema of the source
+            table. ``None`` for function branches.
+        source_table: Catalog-table branch only — the base table name; its
+            presence selects the catalog-table kind. ``None`` for function
+            branches.
         ARROW_SCHEMA: Arrow IPC schema used to (de)serialize this branch over the wire.
 
     """
@@ -2306,6 +2306,8 @@ class ReadOnlyCatalogInterface(CatalogInterface):
         settings: DuckDB setting specs the catalog declares.
         secret_types: Secret type specs the catalog declares.
         attach_option_specs: Attach option specs accepted at ``ATTACH`` time.
+        attach_catalogs: Companion catalogs (lakehouse federation) the client
+            should ATTACH when this catalog attaches.
         catalog: Optional declarative `[`Catalog`][]` object describing the
             catalog's schemas, tables, and views.
         catalog_create: DDL stub that raises `[`CatalogReadOnlyError`][].