This issue is part of the AI Catalog Group Inheritance Epic https://gitlab.com/groups/gitlab-org/-/work_items/22487 see that epic for more context. ### About This builds on the schema from the database issue and teaches the models what the two record kinds mean, and how a flow trigger can belong to a group. There are three parts: 1. `Ai::Catalog::ItemConsumer` gets a `consumer_kind` enum (`direct` and `inheriting`). A record's kind is fixed once created. An `inheriting` record is only valid on a top-level group. We also make sure a group can hold one record of each kind for the same item, so a legacy direct record and a new inheriting record can coexist. 2. `Ai::FlowTrigger` learns that it can belong to a group instead of a project. A group trigger is only allowed when it belongs to an inheriting record for that same group. 3. A feature flag so none of this is visible until we choose to turn it on. With the flag off, everything behaves as it does today. This issue is models, validations, and the feature flag only. The mutations, services, finders, policies, and trigger firing paths that use these models come in later issues, so nothing user-facing changes yet. ### Proposal Scope for this issue: models, validations, lookup scopes, feature flag and factories only. No services, mutations, finders or firing paths. The column is called `kind` (decided in the schema issue #627506), not `consumer_kind`. **`Ai::Catalog::ItemConsumer`** 1. Add `enum :kind, { direct: 0, inheriting: 1 }` (same style as other ai catalog models). 2. Kind is immutable after create: validation on update that rejects `kind_changed?`. 3. `inheriting` only allowed on a top-level group: `group&.root?` must be true. Subgroups are a later iteration. 4. `validate_item_uniqueness` currently checks item + group/project. Scope it by `kind` for group records so a legacy `direct` record and an `inheriting` record for the same item can coexist on a group. Keep project-level uniqueness as it is. 5. Validate that group inheriting records can only be associated with restricted and public items (not private). This is because private visibility means exclusive use for the owner project only. 6. Service account: inheriting records hold their own service account, same as today's top-level group records. `service_account_required?` and `validate_service_account` already cover a root group + flow, so nothing changes there. Assumption: each inheriting record gets its own service account, so `validates :service_account, uniqueness: true` and the unique DB index stay. If we decide to share the legacy record's service account instead, both the validation and the index (schema issue) need to change. **`Ai::FlowTrigger`** 6. `belongs_to :group, optional: true`; `belongs_to :project` becomes `optional: true`; remove `validates :project, presence: true`. Add `validates_with ExactlyOnePresentValidator, fields: [:project, :group]` to mirror the DB check constraint. Note: the validator option is `fields:`, not `attributes:` as the agent plan wrote. 7. Group trigger must belong to an inheriting consumer of the same group: `ai_catalog_item_consumer.inheriting?` and `ai_catalog_item_consumer.group_id == group_id`. This is what keeps a future group-level `direct` kind from ever firing as inherited. 8. `catalog_item_valid` compares `ai_catalog_item_consumer.project != project`. Change it to compare `container` so group triggers are validated too. Add `#container` returning `project || group`. 9. `service_account_id` currently reads `parent_item_consumer&.service_account_id`. Inheriting triggers have no parent, the service account is on the consumer itself. Resolve via `ai_catalog_item_consumer.active_service_account` (already does `service_account || parent_item_consumer&.service_account`) and use its id. No flag needed here since for existing triggers the result is identical. **Lookup scopes** 11. `for_project_root_group(project)`: returns `none` unless `project.root_ancestor` is a `Group`; otherwise joins `ai_catalog_item_consumer`, filters `group_id = root_ancestor.id` and `ai_catalog_item_consumers.kind = inheriting`, and selects `ai_flow_triggers.*` only so it can go into `from_union`. 12. `applicable_to_project(project, triggered_on:, by_service_accounts: nil)`: project triggers as today; if `Feature.enabled?(:ai_catalog_group_inherited_consumers, project.root_ancestor)`, union with `for_project_root_group`. Flag off returns exactly today's relation. 13. Plural variant for the participable (autocomplete) service later: `for_projects_root_groups(project_ids)`, resolving each project's root via `namespaces.traversal_ids[1]` (same pattern as `Namespace.by_root_id`), same inheriting filter. Avoids N+1. 14. Note for the firing paths issue: `registered_for?(project_id, event_type)` only checks `for_projects`, so it will skip inherited triggers. Not changed here, but the firing paths issue must handle it. **Feature flag** 15. `ai_catalog_group_inherited_consumers`, type `gitlab_com_derisk`, actor root group, default off, in `ee/config/feature_flags/gitlab_com_derisk/`. Needs a rollout issue. **Factories** 16. `ai_catalog_item_consumer`: default `kind { :direct }`; add `:inheriting` trait (root group, flow item, service account, same as `:parent_item_consumer` trait but `kind: :inheriting`). 17. `ai_flow_trigger`: add `:for_inheriting_consumer` trait (group set, project nil, consumer from the `:inheriting` trait). **Not in this issue** - Scoping the inherited trigger when a trigger fires, that's in https://gitlab.com/gitlab-org/gitlab/-/work_items/627518+. - Dropping the `kind` DB default. That moves to the services issue, because that's where all the create paths live (`CreateService`, `BulkCreate`, foundational flow sync `insert_all`). One gotcha for whoever does it: `foundational_agents_sql` builds synthesized consumers with `new(...)` and reads every column, so once the default is gone those rows get `kind = NULL` unless `item_consumer_attributes` sets it. - Any change to the "delete existing project enablements when group enables" behaviour. That's the services issue. **Specs** Model specs for the enum, immutability, root-group rule, kind-scoped uniqueness; `FlowTrigger` specs for the group association, exactly-one validation, inheriting-consumer rule, `container`, `service_account_id`, `by_service_accounts` third branch, both scopes, with flag on and off. ### :robot: Agent planning Please see below for the original agent plan (note this plan may not reflect latest plan): <details> <summary>Click to see thinking</summary> #### 1. `Ai::Catalog::ItemConsumer` — the enum and its rules Add the enum. The column is `NOT NULL` from the schema issue, so all rows already have a kind. ```ruby enum :consumer_kind, { direct: 0, inheriting: 1 } ``` Rules to enforce: - **Immutable after create.** A record's kind should never change. Simplest is a validation that rejects a change on a persisted record: ```ruby validate :consumer_kind_unchanged, on: :update def consumer_kind_unchanged return unless consumer_kind_changed? errors.add(:consumer_kind, _('cannot be changed')) end ``` - **`inheriting` requires a top-level group.** An inheriting record makes no sense on a project, and this iteration only supports top-level groups (subgroup support is a separate future task). ```ruby validate :inheriting_only_on_top_level_group def inheriting_only_on_top_level_group return unless inheriting? errors.add(:base, _('Inheritance is only supported for a top-level group')) unless group&.root? end ``` - **Uniqueness scoped by kind.** Today there is a uniqueness rule that a given item can only be enabled once per group/project. We need to let a group hold one `direct` record (the legacy service-account-holder) and one `inheriting` record for the same item at once, so add `consumer_kind` to the scope of that uniqueness check. Look at the existing `validate_item_uniqueness` (or equivalent) and make the scope include `consumer_kind` for group records. Take care not to loosen the project-level uniqueness. Convenience: the `enum` gives us `direct?` / `inheriting?` predicates and `direct` / `inheriting` scopes, which later issues rely on. #### 2. `Ai::FlowTrigger` — group association and validations Add the association: ```ruby belongs_to :group, optional: true ``` `project` is now `optional: true` too (from the schema change). Enforce "exactly one of project or group" in the model to match the DB CHECK constraint. The codebase has an `ExactlyOnePresentValidator` used elsewhere for this shape, prefer that over hand-rolling: ```ruby validates_with ExactlyOnePresentValidator, attributes: %i[project group] ``` (Check the exact validator name/signature in the codebase and match existing usage.) Then, a group trigger must belong to an inheriting record for the same group. This keeps group triggers strictly tied to inheriting, so if we later add a group-level `direct` kind, those would not accidentally fire as inherited triggers: ```ruby validate :group_trigger_belongs_to_inheriting_consumer def group_trigger_belongs_to_inheriting_consumer return if group_id.nil? consumer = ai_catalog_item_consumer unless consumer&.inheriting? && consumer.group_id == group_id errors.add(:base, _('A group trigger must belong to an inheriting consumer of the same group')) end end ``` Add a `#container` helper returning `project || group`, mirroring `ItemConsumer#container`, since call sites will want the owning container without caring which it is. #### 5. `#service_account` / `#service_account_id` These resolve the acting service account for a trigger. Inheriting triggers resolve theirs from the inheriting consumer. Gate any new inheriting-aware branch behind the feature flag so, with the flag off, resolution is unchanged. Confirm the current method bodies before editing. #### 6. Feature flag Add `ai_catalog_group_inherited_consumers`, actor-based on the root group (`gitlab_com_derisk` rollout type), default off. #### 7. Factories - `ai_catalog_item_consumer`: default `consumer_kind: :direct`; add an `:inheriting` trait that sets a top-level group and reuses the flow service-account setup the existing group factory uses. - `ai_flow_trigger`: add a trait for a group inheriting trigger (group set, project nil, attached to an inheriting consumer). #### Testing - Model specs for the enum, immutability, top-level-group requirement, and kind-scoped uniqueness. - `FlowTrigger` specs for the group association, exactly-one-of validation, the inheriting-consumer invariant, `for_project_root_group` (and the plural variant), `by_service_accounts` third branch, and `applicable_to_project` with the flag on and off. - Keep everything green with the flag off to confirm no behaviour change. </details>