@spec catalogue_reference_count(Ecto.UUID.t()) :: non_neg_integer()

Returns the count of rules referencing a given catalogue (non-deleted items only). Cheaper than list_items_referencing_catalogue/1 when you just need a badge number.

@spec catalogue_rule_map(PhoenixKitCatalogue.Schemas.Item.t() | Ecto.UUID.t()) :: %{
  required(Ecto.UUID.t()) => PhoenixKitCatalogue.Schemas.CatalogueRule.t()
}

Returns the rules for an item as %{referenced_catalogue_uuid => rule}.

Convenient for picker UIs that render every available catalogue row and need O(1) lookup for "is this one checked?". Preloads the referenced catalogue on each rule.

@spec change_catalogue_rule(PhoenixKitCatalogue.Schemas.CatalogueRule.t(), map()) ::
  Ecto.Changeset.t(PhoenixKitCatalogue.Schemas.CatalogueRule.t())

Returns a changeset for tracking a single rule's changes.

@spec create_catalogue_rule(
  map(),
  keyword()
) ::
  {:ok, PhoenixKitCatalogue.Schemas.CatalogueRule.t()}
  | {:error, Ecto.Changeset.t(PhoenixKitCatalogue.Schemas.CatalogueRule.t())}

Inserts a single rule. Prefer put_catalogue_rules/3 for managing an item's full set of rules; this function exists for surgical edits.

@spec delete_catalogue_rule(
  PhoenixKitCatalogue.Schemas.CatalogueRule.t(),
  keyword()
) ::
  {:ok, PhoenixKitCatalogue.Schemas.CatalogueRule.t()}
  | {:error, Ecto.Changeset.t(PhoenixKitCatalogue.Schemas.CatalogueRule.t())}

Deletes a single rule.

@spec get_catalogue_rule(Ecto.UUID.t(), Ecto.UUID.t()) ::
  PhoenixKitCatalogue.Schemas.CatalogueRule.t() | nil

Fetches a single rule by {item_uuid, referenced_catalogue_uuid}. Returns nil if not found. Does not preload the referenced catalogue.

@spec list_catalogue_rules(PhoenixKitCatalogue.Schemas.Item.t() | Ecto.UUID.t()) :: [
  PhoenixKitCatalogue.Schemas.CatalogueRule.t()
]

Lists the rules attached to an item, ordered by position then by the referenced catalogue's name. The :referenced_catalogue association is preloaded so UIs can render the catalogue name + status without a second query.

Smart items are the only ones that should have rules; a standard item simply returns [] unless someone put rules on it manually.

@spec list_items_referencing_catalogue(Ecto.UUID.t()) :: [
  PhoenixKitCatalogue.Schemas.Item.t()
]

Lists non-deleted smart items that reference a given catalogue.

Useful for warning-before-delete flows: "This catalogue is referenced by 3 smart items — deleting it cascades to those rules."

Preloads the parent catalogue so the UI can render "Services / Delivery".

@spec put_catalogue_rules(PhoenixKitCatalogue.Schemas.Item.t(), [map()], keyword()) ::
  {:ok, [PhoenixKitCatalogue.Schemas.CatalogueRule.t()]}
  | {:error, {:duplicate_referenced_catalogue, Ecto.UUID.t() | nil}}
  | {:error, Ecto.Changeset.t(PhoenixKitCatalogue.Schemas.CatalogueRule.t())}

Atomic replace-all for an item's rules. See moduledoc for context.

@spec update_catalogue_rule(
  PhoenixKitCatalogue.Schemas.CatalogueRule.t(),
  map(),
  keyword()
) ::
  {:ok, PhoenixKitCatalogue.Schemas.CatalogueRule.t()}
  | {:error, Ecto.Changeset.t(PhoenixKitCatalogue.Schemas.CatalogueRule.t())}

Updates a single rule's value/unit/position.