@spec failed_sync_work(
  module(),
  keyword()
) ::
  {:ok, [Scrypath.Operator.FailedWork.t()]}
  | {:ok, Scrypath.Operator.FailedSyncWorkInspection.t()}
  | {:error, term()}

Returns failed or retrying sync work rows for a schema.

Reason class rollups

Pass reason_class_counts: true in operator options (alongside runtime config) to receive {:ok, %Scrypath.Operator.FailedSyncWorkInspection{}} with entries (the row list) and counts — a %Scrypath.Operator.ReasonClassCounts{} with dense per-class frequencies. The default remains {:ok, [FailedWork.t()]} when this option is omitted.

@spec index_contract_drift(
  module(),
  keyword()
) :: {:ok, Scrypath.Operator.IndexContractDrift.Report.t()} | {:error, term()}

Read-only index contract drift report for a searchable schema.

Compares declared schema metadata and resolved settings against a single live Meilisearch GET /indexes/{uid}/settings snapshot. This is a report-first operator surface: it does not enqueue work, mutate indexes, or imply recovery actions. It is not the same signal family as reconcile_sync/2's drift_signals, which reflects sync queue and reindex posture.

See include_index_contract_drift: true on reconcile_sync/2 when you want the same report attached to a reconcile tuple (adds one get_settings read).

@spec reconcile_sync(
  module(),
  keyword()
) :: {:ok, Scrypath.Operator.Reconcile.t()} | {:error, term()} | {:ok, map()}

Report-first reconciliation for a schema (sync visibility, failed work, drift signals, and suggested recovery actions).

Index contract drift

Pass include_index_contract_drift: true alongside runtime options to attach a read-only %Scrypath.Operator.IndexContractDrift.Report{} on index_contract_drift. This performs an extra Meilisearch get_settings read using the same builder as index_contract_drift/2. Omit the flag (default) to avoid that latency and live dependency.

@spec schema_faceting(module()) :: keyword()

Returns normalized faceting: options for the schema, or [] when faceting is disabled.

Shape when enabled is a keyword list with :attributes, :max_values_per_facet, and :sort_facet_values_by.

@spec search_many(
  list(),
  keyword()
) :: {:ok, term()} | {:error, term()}

Federated search across multiple schemas.

Returns an ok tuple whose success value is the library's federated multi-search result struct, or an error tuple on validation, transport, or complete failure.

@spec search_within_facet(module(), String.t(), {atom(), term() | list()}, keyword()) ::
  {:ok, term()} | {:error, term()}

Full-text search scoped to a single facet bucket, AND-combined with any other filter:, facet_filter:, sort, and pagination options.

facet_bucket is {facet_attribute, value} where value is either a scalar (one bucket) or a list interpreted as OR within that attribute, matching facet_filter: encoding. Passing the same attribute again under facet_filter: is rejected with ArgumentError — use search/3 or keep only one source of truth.