Inherited grants, plus the sync-mode grant correctness fixes found applying them

[noel]

Adds support for Snowflake's inherited grants, and fixes eight bugs found while migrating a real config (datacoves/balboa) onto them against a production account.

The bugs are not specific to inherited grants — they are sync-mode grant bugs that the migration happened to walk into. Most of them share one root cause: the config declares a grant one way and Snowflake reports it another, so declared state and remote state never match. In --sync_resources mode any grant a managed role holds that isn't declared becomes a DROP, so a mismatch is not cosmetic: it produces a permanent DROP+CREATE pair that never converges, and in the worst case revokes access that was declared.

Inherited grants

GRANT INHERITED <priv> ON ALL <items> IN <container> replaces the ALL + FUTURE pair with a single durable record covering current and future objects.

• feat(grants): support Snowflake inherited grants — the grant form itself
• feat(grants): let config enable the inherited grants preview itself — FEATURE_RBAC_INHERITED_GRANTS is settable from the account resource, so a config can turn on the preview it depends on
• fix(grants): tolerate inherited grants in remote state — inherited grants read back cleanly even in configs that don't declare any
• feat(grants): warn when database-level future grants are shadowed or at risk — schema-level future grants silently shadow database-level ones; this surfaces it rather than letting coverage disappear
• docs(grants): correct what Snowcap can and cannot enable — the account parameter is only half of it; the preview also needs account-wide access from Snowflake

Grant identity: declared vs. observed

• Identify grants by the object name their DDL uses, not the one SHOW GRANTS reports — SHOW GRANTS says CORTEX_AGENT_SERVER for the object that GRANT and CREATE call an MCP SERVER. Same object, two names, so every plan produced a DROP+CREATE for it. Grants are now keyed on the DDL spelling on every emission path.
• Stop listing database role grants as object grants — a grant of a database role was being read back as a USAGE grant on one, so applying it emitted GRANT USAGE ON DATABASE ROLE, which Snowflake rejects outright (391811 Unsupported feature).
• Do not list the usage a database role is born with — creating a database role grants it USAGE on its own database. That grant has an empty granted_by, is timestamped with the CREATE, and cannot be revoked. It was being listed as an undeclared grant, so every plan tried to drop it and every apply silently failed.
• Read future grants when syncing (part of a28979c) — remote state for synced types comes only from list_*, and list_grants wasn't asking for future grants. Declared future grants therefore looked absent and were re-created on every run. Also in this commit: IMPORTED PRIVILEGES is reported as USAGE on share-backed databases, and the fetch_* synonym path is aligned with list_*.

Execution role

• Create resources inside a container this plan transfers as its new owner — when a plan transfers ownership of a database and creates objects inside it, the creates were being run as the old owner and failed with 003001 Insufficient privileges. The new owner is now used for creates that land inside a container the same plan transfers.
• Revoke account-level privileges as the system role that owns them — system_role_for_priv was applied to CreateResource but not DropResource, so five revokes ran as a role that could not perform them. Snowflake returned SUCCESS for all five and carried out none.
• Revoke the share when dropping a grant on a shared database — individual privileges on an imported database cannot be revoked (003028); the share grant itself has to go.

Surfacing drops Snowflake accepts but doesn't perform

Report drops Snowflake accepted without carrying out adds a post-apply verification pass: after a non-dry-run apply, each destructive change is re-checked against the account, and any grant still present is reported.

This is what turned the two silent-revoke bugs above from "the plan keeps showing the same drops and nobody knows why" into a named, actionable warning. It is deliberately a diagnostic rather than a hard failure — some survivors are legitimate (the intrinsic database-role usage above is unrevokable by design).

YAML

Let YAML grant a database role to another database role — to_database_role was reachable from the Python API but had no YAML spelling, so composing database roles (the normal way to build a reader/writer hierarchy) required dropping out of config. The loader now accepts singular and plural forms consistently across database_role_grants.

Other

• feat(gitops): add a where filter to for_each
• docs(rbac): document the cloned-database grant pattern
• ci: move workflow actions off deprecated Node 20 runtimes
• style: make formatting and spelling checks enforceable

Testing

2005 tests passing, up from 1934 on main. Every fix above carries a regression test written against the shape of the real remote-state row that caused it.

Beyond the suite, each fix was verified by running plan and apply against the production Snowflake account the balboa config manages, iterating until plan reached a clean state — which is how the silent-revoke bugs were found in the first place, since they are invisible to any test that trusts Snowflake's return status.

Merge order

This should merge before datacoves/balboa#283, which migrates that config to inherited grants and depends on these fixes to apply cleanly.

🤖 Generated with Claude Code

https://claude.ai/code/session_01DtvxdHFZzsbwDHtr13CTkH

---

Generated by Claude Code

[github-actions]

Review — no comment produced this round

The review job finished without producing findings (job log). A maintainer may want to re-run it.

[github-actions]

Review — no comment produced this round

The review job finished without producing findings (job log). A maintainer may want to re-run it.

[github-actions]

Review — no comment produced this round

The review job finished without producing findings (job log). A maintainer may want to re-run it.

[github-actions]

Review — no comment produced this round

The review job finished without producing findings (job log). A maintainer may want to re-run it.

[github-actions]

Review — no comment produced this round

The review job finished without producing findings (job log). A maintainer may want to re-run it.

[github-actions]

Review of PR #58

Correctness

1. snowcap/data_provider.py:1012 — The @cache decorator that previously sat directly on fetch_session (confirmed via git show origin/main:snowcap/data_provider.py, where @cache sits at line 758 immediately above def fetch_session) now decorates the newly-inserted fetch_inherited_grants_enabled instead; fetch_session (line 1073) lost its memoization entirely. This has two consequences:

   • fetch_session is called multiple times per logical operation (blueprint.py:1581, 2089, 2233, data_provider.py:743), so a single plan()/apply() now re-issues the session query (CURRENT_ACCOUNT_NAME(), CURRENT_AVAILABLE_ROLES(), etc.) instead of reusing one cached result — a real perf regression and a risk that role/session data drifts mid-run.
   • fetch_inherited_grants_enabled is now double-cached: it keeps its own manual _INHERITED_GRANTS_ENABLED_CACHE dict (cleared by reset_account_usage_caches() at line 1230), but the outer functools.cache wrapper short-circuits the entire function body — including the manual-cache-clear check — for a given session object, so reset_account_usage_caches() can no longer actually invalidate this value. A process that calls plan()/apply() more than once on the same session (e.g. plan → apply → plan) will keep using a stale "inherited grants enabled" verdict.
     Fix: put @cache back on fetch_session, and drop it from fetch_inherited_grants_enabled (which already has its own invalidatable cache).

2. snowcap/blueprint.py:2469 vs. 2478 (execution_strategy_for_change) — For grant/revoke changes, the system_role_for_priv(grant_data["priv"]) check (line 2469-2473) runs and returns before the new database-role-grantee check (_database_of_database_role_grantee / database_owners, line 2478-2482) is ever reached. If a config grants/revokes an AccountPriv that has a default system-role owner (e.g. MANAGE GRANTS → SECURITYADMIN, CREATE WAREHOUSE/CREATE DATABASE → SYSADMIN) to a DATABASE ROLE grantee, the system role is picked first even though it may lack USAGE on the grantee's database. Per the comment at 2475-2477, that's exactly the case this new code path is meant to prevent: Snowflake reports the REVOKE as successful without applying it, reproducing the "surviving drop" bug this PR otherwise adds surviving_drops() to detect — except here it's produced by this PR's own new ordering. Consider moving the database-role-grantee check before the system_role_for_priv check, or making the two mutually exclusive based on grantee type.

Minor / worth a look

3. snowcap/blueprint.py:1008 — _format_grant_name still pluralizes FUTURE/ALL/INHERITED display text with a naive items_type_str + "S", while this same diff introduces inflection.pluralize for the equivalent text in future_grant_precedence_warnings (lines 381, 407) and in resources/grant.py/lifecycle.py for the actual generated SQL. For an irregular plural (e.g. POLICY), the plan diff line would show "POLICYS" while the executed SQL and precedence warnings correctly say "POLICIES" for the same grant — a cosmetic but confusing mismatch between what the plan displays and what runs. Worth swapping in pluralize() here too for consistency.

4. snowcap/blueprint.py:2532-2545 — The new TransferOwnership branch for OWNER_EXECUTED_RESOURCE_TYPES unconditionally routes through SECURITYADMIN whenever it's in available_roles, with no fallback to the previous owner-based change_owner path if that specific transfer fails (e.g. an account that has deliberately stripped MANAGE GRANTS from SECURITYADMIN). Low risk in the common case, but worth confirming this is the intended tradeoff since it forecloses the previously-working fallback for that resource class.

Nothing else stood out as a likely correctness issue; the bulk of the diff (inherited-grants support, future-grant precedence warnings, surviving_drops detection) reads as a coherent, well-tested fix for the underlying "REVOKE reports success but silently no-ops" class of bug, and follows the existing ResourceSpec/helper-function patterns used elsewhere in blueprint.py.

[github-actions]

Review — no comment produced this round

The review job finished without producing findings (job log). A maintainer may want to re-run it.

[github-actions]

Review of PR #58

snowcap/data_provider.py:2333 — _inherited_grant_matches skips the synonym normalization this same PR just added for the identical problem.
This diff introduces _granted_on_label() (data_provider.py:290) specifically because Snowflake's SHOW GRANTS/inherited-grant rows report synonym object types under a different name than the manifest's canonical ResourceType (its own docstring gives the example: CORTEX_AGENT_SERVER vs. the manifest's MCP_SERVER), and the diff also applies the equivalent fix to future grants via _normalize_future_grant_name. But _inherited_grant_matches (used by fetch_inherited_grant) still does a raw grant["granted_on"].replace("_", " ").upper() != items_type... string comparison instead of routing through _granted_on_label/resource_type_for_label. A declared Grant(priv="SELECT", on="INHERITED MCP SERVERS IN DATABASE somedb", to=role) will never match the remote row reported as CORTEX_AGENT_SERVER, so it's reissued on every apply, and surviving_drops (same fetch path) can never confirm a real drop of that type either.

snowcap/var.py:126 — the var./parent. guard regex is bypassable with whitespace, defeating the safety check it was added for.
re.search(r"\b(?:var|parent)\.", condition) requires the dot to immediately follow the identifier, but Jinja's expression grammar tolerates whitespace before an attribute-access dot. Verified directly:

>>> jinja2.Environment().compile_expression('var . x == 1')(var=VarStub())
False

A where: "var . env == 'prod'" slips past the guard, and var.env resolves through VarStub to the literal string "{{ var.env }}", silently returning a wrong-but-truthy/falsy result instead of raising MissingVarException — exactly the "declared grants silently become DROPs in sync mode" failure the guard's own docstring (var.py:121-125) says it exists to prevent.

snowcap/var.py:134 — evaluate_for_each_where only catches jinja2.exceptions.UndefinedError; other evaluation errors escape both this function and its caller's error collection.
gitops.py's per-item try/except around this call (gitops.py:277) only catches (InvalidKeyException, ValueError, MissingVarException), and the outer per-resource try/except (gitops.py:290) catches the same set. A where expression like each.value.count > 'text' that raises a native TypeError (e.g. comparing an int to a str when for_each items are inconsistently typed) is caught by neither layer, so it aborts the entire config load instead of being collected as that one item's validation error, contradicting the inline comment at gitops.py:249-251 ("Inside the try so a bad where ... is collected as this item's validation error instead of aborting the entire for_each block").

snowcap/blueprint.py:2402 and :2469 — two new helpers parse dotted identifiers with a plain str.split(".")[0] instead of the quote-aware smart_split this same PR introduces for the identical problem.
_container_covers (blueprint.py:411-421, new in this diff) explicitly switches to smart_split(object_name, ".") with the comment "a plain str.split would miscount and mis-classify" a quoted identifier containing a literal dot. But the sibling functions added in the same diff — _shared_database_for_grant (database = str(on).split(".")[0].strip('"').upper(), line 2402) and _database_of_database_role_grantee (grantee.split(".")[0].strip('"').upper(), line 2469) — still use the naive split. A shared database or database-role name containing a literal dot inside quotes (e.g. "my.shared.db") is mis-split to "my, so _shared_database_for_grant fails to route the revoke through drop_shared_database_grant, and _database_of_database_role_grantee fails to route grant execution to the owning database's role.

snowcap/blueprint.py:2508-2513 — the new database-role-grantee execution-role routing only fires for Create/Drop grant changes, not Update.
_database_of_database_role_grantee (called at blueprint.py:2509) returns None unless isinstance(change, (CreateResource, DropResource)) (see its own branching at blueprint.py:2458-2463), so for an UpdateResource grant change it always returns None and the call falls through to the generic SECURITYADMIN fallback a few lines down. grant_option is not part of the grant's FQN (grant_fqn, resources/grant.py:561-579, keys only on grant_type/priv/on/to), so toggling grant_option on an existing grant produces an UpdateResource, not a Create+Drop pair. For a grant to a database role, SECURITYADMIN can hold MANAGE GRANTS yet still be unable to resolve the grantee without USAGE on its database — which is exactly the silent-no-op class of bug (REVOKE/GRANT reports success without effect) this PR's _database_of_database_role_grantee was added to fix for Create/Drop, just not for Update.

snowcap/data_provider.py:1012-1013 — fetch_inherited_grants_enabled is both @cached and manually cached; reset_account_usage_caches() only clears the manual cache.
The function is decorated with @cache (functools) and keeps its own _INHERITED_GRANTS_ENABLED_CACHE dict keyed by id(session). reset_account_usage_caches() (data_provider.py:1214-1230) clears the manual dict but never calls fetch_inherited_grants_enabled.cache_clear(). If a session object is reused across two plan()/apply calls in the same process (e.g. a long-lived test harness or service), the second call always returns the first call's stale result via the outer functools.cache, even after an explicit cache reset — so raise_if_inherited_grants_unavailable can keep blocking (or allowing) applies based on stale account state.

Minor / lower-confidence:

• snowcap/gitops.py:59 — _as_list does values.extend(config.get(plural) or []) with no type check. A YAML typo like roles: bob (string instead of a list) silently iterates the string into three single-character grant targets ('b', 'o', 'b') rather than raising a clear config error.
• snowcap/blueprint.py:224-260 — manifest_has_future_grants, manifest_future_grant_roles, and manifest_future_grant_database_roles appear to be dead code now: their only call site was removed when the sync-resources path switched to unconditionally passing include_future_grants=True. No remaining references in snowcap/ or tests/. Worth deleting or confirming there's a planned caller.

[github-actions]

Review of PR #58

snowcap/data_provider.py:1012-1013 — @cache landed on the wrong function, silently un-caching fetch_session and permanently caching fetch_inherited_grants_enabled.
On main (git show origin/main:snowcap/data_provider.py:758), @cache decorated fetch_session directly. This PR inserted fetch_inherited_grants_enabled/fetch_preview_access_enabled between the decorator and fetch_session, so @cache now applies to fetch_inherited_grants_enabled (data_provider.py:1013) and fetch_session (data_provider.py:1073) is left uncached.

• tests/integration/data_provider/test_list_resource.py:102 calls data_provider.fetch_session.cache_clear() as its first statement — this now raises AttributeError since fetch_session is a plain function.
• fetch_inherited_grants_enabled gets an unbounded functools.cache on top of its own manual _INHERITED_GRANTS_ENABLED_CACHE dict, which is cleared by reset_account_usage_caches() (data_provider.py:1230). The outer functools.cache has no .cache_clear() caller anywhere, so a reused session keeps a stale enabled/disabled answer forever, even across an explicit cache reset.

snowcap/resources/grant.py:449-460 — INHERITED grants never get a requires() dependency edge on their container, unlike FUTURE grants.
granted_in_ref is only set if grant_type == GrantType.FUTURE: (lines 449-450, 459-460); self.requires(granted_in_ref) (line 500) is the only thing that would order the grant after its database/schema. A manifest that declares a new database/schema together with on: INHERITED TABLES IN DATABASE ... on it in the same apply has no dependency edge forcing the grant after the CREATE DATABASE/CREATE SCHEMA, so compute_levels can place the GRANT INHERITED ... at the same or an earlier level, and the apply can fail because the container doesn't exist yet. The new feature-flag wiring (_link_inherited_grants_to_feature_flag, blueprint.py) links the grant to the RBAC feature flag but not to the container itself, and tests/test_blueprint.py::TestInheritedGrantPlanning::test_inherited_grants_are_applied_after_the_feature_flag doesn't assert level ordering against the database, so this path is untested.

snowcap/gitops.py:44-61 — _as_list silently explodes a mistakenly-scalar plural key into per-character grant targets instead of erroring.
values.extend(v for v in (config.get(plural) or []) if v not in (None, "")) iterates whatever config.get(plural) returns. If a user writes roles: analyst (forgetting the list dash) instead of roles: [analyst], config.get("roles") is the string "analyst", which is iterable, so this yields one grant per character. Reproduced directly:

_resources_from_database_role_grants_config([{'database_role': 'somedb.somerole', 'roles': 'analyst'}])

produces 7 DatabaseRoleGrants to roles A, N, A, L, Y, S, T with no exception. This is new in this PR (_as_list is a new helper, used both by the pre-existing roles/to_role path and the new database_roles/to_database_role path at gitops.py:191-195) — a bad YAML indent now silently plans nonsense single-letter-role grants instead of failing.

snowcap/data_provider.py:2333-2336 — _inherited_grant_matches skips the synonym normalization applied everywhere else in this same PR, so fetch_inherited_grant disagrees with list_grants for synonym object types.
_granted_on_label (data_provider.py:290-312) was added in this PR specifically because Snowflake reports some object types under a different name than their DDL (e.g. CORTEX_AGENT_SERVER for what the manifest calls MCP_SERVER), and is used consistently in _fetch_grant_to_role and list_grants. _inherited_grant_matches, used by fetch_inherited_grant, instead does a raw grant["granted_on"].replace("_", " ").upper() != items_type.replace("_", " ").upper() with no ResourceType/synonym resolution. A declared INHERITED grant on mcp_server whose underlying Snowflake row reports granted_on="CORTEX_AGENT_SERVER" never matches here, so fetch_inherited_grant reports the grant as missing even though list_grants (which does normalize) reports it as present — plan/apply can treat an existing inherited grant as absent.

snowcap/data_provider.py:2398-2404 — fetch_grant's priv == "ALL" branch wasn't updated with the same synonym fix applied to its sibling branch.
The else branch just below (line ~2416, _fetch_grant_to_role) and list_grants both compare object types via _granted_on_label(...). The ALL branch still builds filters = {"granted_on": on_type} and passes it straight to _filter_result with no normalization. GRANT ALL ON MCP_SERVER ... TO ROLE r (on_type="MCP_SERVER") never matches a SHOW GRANTS row reporting granted_on="CORTEX_AGENT_SERVER", so fetch_grant returns nothing and plan/apply proposes (re-)creating the ALL grant on every run.

snowcap/data_provider.py:257-263 — _is_intrinsic_database_role_usage compares plain strings instead of using ResourceName, unlike the quote-aware fix this same PR applies elsewhere (e.g. _fetch_grant_to_role's "Use ResourceName for comparison to handle quoted identifiers correctly").
return str(row["name"]).upper() == grantee.split(".")[0].upper(). The caller builds fq_db_role_name = f"{db_role_fqn.database}.{db_role_fqn.name}" where db_role_fqn.database is a ResourceName; str() on a quoted ResourceName embeds literal double quotes (resource_name.py:61-62). For a database created as CREATE DATABASE "analytics", fq_db_role_name becomes '"analytics".MY_ROLE', so grantee.split(".")[0].upper() is '"ANALYTICS"' (quotes included) while SHOW GRANTS reports the bare name "analytics" → "ANALYTICS". The comparison never matches, so the intrinsic un-revokable USAGE grant this function exists to filter out (per its own docstring) leaks into remote state, and sync proposes dropping it every run, forever, for any quoted/case-sensitive database name.

snowcap/blueprint.py:224,241,594 — manifest_has_future_grants, manifest_future_grant_roles, and manifest_future_grant_database_roles are now dead code.
The diff changed Blueprint.plan's only call site to unconditionally set list_kwargs['include_future_grants'] = True instead of using these helpers to narrow the query. No remaining callers exist anywhere in snowcap/ or tests/ — worth deleting rather than leaving unused.

Everything else in the diff (INHERITED grant SQL rendering in lifecycle.py, the plan-levels plumbing in operations/blueprint.py/cli.py, var.py's evaluate_for_each_where, and the ResourceType synonym table in enums.py) checked out correctly against direct testing.

[github-actions]

Review — no comment produced this round

The review job finished without producing findings (job log). A maintainer may want to re-run it.