[CXH-2721] - Add Unity Catalog catalog sync and catalog scoping config - Databricks Connector

[mateoHernandez123]

Description

• Bug fix
• New feature

Second of four stacked PRs for Unity Catalog. Adds the catalog resource type and the two config fields that scope a Unity Catalog sync (CXH-2721).

A catalog's parent is the metastore that owns it, not the workspace it is read through. The workspace host is an access path, resolved per call by the routing added in #70 — a catalog listed through two workspaces is one resource, not two.

Resource hierarchy

account
├── workspace
│   └── role (workspace-level)
├── user
├── group
├── service principal
├── role (account-level)
└── metastore
    └── catalog
        └── schema
            ├── table
            └── volume

This PR delivers the catalog level.

Stack position

This PR is #2 of 4 and is based on branch 1, not on main. #70 has to merge first; once it does I will retarget this PR's base to main. Everything in the diff below branch 1's commit belongs to branch 1.

Order	PR	Branch	Base
1	#70 — Unity Catalog client, access-path routing, metastore sync	mateoHernandez123/unity-catalog-foundation-and-metastore	main
2	#71 — catalog sync and catalog scoping config	mateoHernandez123/unity-catalog-catalog-sync	branch 1
3	#72 — schema sync	mateoHernandez123/unity-catalog-schema-sync	branch 2
4	#73 — table and volume sync	mateoHernandez123/unity-catalog-table-and-volume-sync	branch 3

Sync:

• Catalogs (catalog, NEW) — child of metastore. Listed through every workspace attached to the metastore and unioned, because an ISOLATED catalog is only listable from the workspaces bound to it. Keyed {metastore_id}::{name}, so the same catalog reached through two workspaces derives one resource id. One entitlement per catalog-level privilege plus the read-only owner.
• A catalog that is listed but that no workspace in this sync can reach is an error rather than an omission: emitting it as absent would tell C1 to delete it and everything under it.
• Metastores (metastore) — unchanged from branch 1
• Users, groups, service principals, roles, workspaces, account — unchanged surface

Provisioning:

• Grant/Revoke catalog privileges — NEW, same PATCH .../permissions/catalog/{name} path and the same echo-confirmed idempotency as the metastore level: GrantAlreadyExists / GrantAlreadyRevoked come off the echoed assignments, not off the HTTP status.
• Owner is not grantable at this level either.
• Everything else — unchanged

Auth:

Unchanged credentials. Two new optional fields, mutually exclusive:

• --databricks-catalogs (BATON_DATABRICKS_CATALOGS) — sync only these catalogs, by name.
• --databricks-exclude-catalogs (BATON_DATABRICKS_EXCLUDE_CATALOGS) — sync everything except these.

Not a breaking change: both default to empty, which syncs every catalog. One entry scopes a whole subtree, since schemas, tables and volumes are all listed through their catalog. Matching is case-insensitive because Unity Catalog resolves catalog names case-insensitively. The filter is applied when catalogs are collected, so an out-of-scope catalog is absent in exactly the way a deleted one is, rather than surfacing as unreachable.

Architecture highlights:

• The filter is re-checked in New() as well as declared mutually exclusive in the config schema, because New() is exported and a caller can bypass the SDK's check.
• A filter entry that matches no catalog is logged by name at Debug — a typo in the list otherwise looks exactly like a filter that is working.
• Catalog paging emits over a name-sorted union of every attached workspace and carries the last name emitted as its cursor rather than an offset, so a resumed sync in a fresh process picks up where it left off.

What is and is not verified

Being explicit so nobody reads more into this than it earned.

Verified. The full stack applied together was run against a ConductorOne tenant in Squire several times. Sync completed clean, the metastore → catalog → schema → table/volume hierarchy landed with the expected parents, direct grants landed on the right principals, and grants reaching a user through a group surfaced as expanded grants in C1.

Not verified. The four cuts were not validated individually — the validation was always against the whole stack. Each branch builds, tests and lints on its own and the capabilities/config metadata matches its own binary, but no one has run a C1 sync against branch 1, 2 or 3 in isolation.

Not verified, specifically. The view case — a view rejecting ALL_PRIVILEGES with a 400 even though the documentation lists it — is covered by a unit test and by the privilege sets, but it was never exercised against a live tenant: the Databricks account ran out of credits and no SQL warehouse would start, so no view or materialized view could be created to grant against.

Useful links:

• Linear ticket CXH-2721 — Unity Catalog catalog sync and scoping config
• Databricks — list catalogs
• Databricks — update permissions on a securable

[linear-code]

CXH-2721