@spec execute_bulk_create(module(), [map()], map(), keyword()) ::
  {:ok, [map()]} | {:error, non_neg_integer(), Ecto.Changeset.t()}

Bulk insert multiple records using Ecto.Multi for individual changeset validation. Returns {:ok, records} or {:error, index, changeset}.

@spec execute_bulk_delete(module(), map(), map(), keyword()) ::
  {:ok, non_neg_integer()}
  | {:ok, non_neg_integer(), [map()]}
  | {:error, term()}

Bulk delete records matching query filters. Returns {:ok, count} or {:ok, count, records} when returning.

@spec execute_bulk_update(module(), map(), map(), map(), keyword()) ::
  {:ok, non_neg_integer()}
  | {:ok, non_neg_integer(), [map()]}
  | {:error, term()}

Bulk update records matching query filters. Returns {:ok, count} or {:ok, count, records} when returning.

@spec execute_create(module(), map(), map()) ::
  {:ok, map()} | {:error, Ecto.Changeset.t()}

Executes a create (POST) pipeline: build changeset, insert, apply after_load.

@spec execute_delete(module(), term(), map()) ::
  {:ok, map()} | {:error, :not_found | Ecto.Changeset.t()}

Executes a delete (DELETE) pipeline: find by PK within scope, delete.

@spec execute_read(module(), map(), map(), keyword()) ::
  {:ok, [map()]} | {:ok, [map()], map()} | {:error, term()}

Executes a read (GET) pipeline: parse params, apply scope/filters/select/order/pagination, fetch records.

Returns {:ok, records} or {:ok, records, range_info} when count mode is requested.

@spec execute_update(module(), term(), map(), map()) ::
  {:ok, map()} | {:error, :not_found | Ecto.Changeset.t()}

Executes an update (PATCH) pipeline: find by PK within scope, apply changeset, update.

@spec execute_upsert(module(), map() | [map()], map(), keyword()) ::
  {:ok, non_neg_integer()}
  | {:ok, non_neg_integer(), [map()]}
  | {:error, term()}

Upsert records using Ecto's on_conflict support. Returns {:ok, count} or {:ok, count, records} when returning.

@spec normalize_keys(map(), [atom()]) :: map()

Converts string-keyed JSON attrs to atom-keyed maps, filtering to known schema fields.