@spec after_commit((-> term())) :: :ok

Defers a cache invalidation or compatibility-settings sync until this module's outer transaction commits. Callbacks are best effort. Inside a caller-owned repo transaction it retains the callback's existing immediate behavior; callers needing commit ordering must use transaction/1 as their outer boundary.

@spec bucket_fields() :: [atom()]

The bucket fields whose changes are recorded: never a key or a secret.

@spec change(struct(), (struct() -> result)) :: result | {:error, term()}
when result: var

Locks and reloads an audited resource so diffs describe its actual preceding state.

@spec changes(Ecto.Changeset.t(), [atom()]) :: %{required(String.t()) => map()}

The "changes" map of an update: for each of fields that the changeset changes, %{"field" => %{"from" => old, "to" => new}} (values made loggable). Empty when nothing in fields changed.

@spec damaged_copies(term(), pos_integer()) :: %{
  count: non_neg_integer(),
  last_at: term()
}

How many damaged copies were found in the bucket in the last days days (distinct object keys among the storage.copy.damaged entries, so verifying the same copy twice counts it once), and when the last was: %{count:, last_at:}.

@spec diff(map(), map(), [atom()]) :: %{required(String.t()) => map()}

The "changes" map between two values of the same struct (before, after) for fields. Empty when none differs.

@spec log(String.t(), String.t(), String.t() | nil, keyword(), map()) ::
  {:ok, PhoenixKit.Activity.Entry.t()} | {:error, term()} | :skipped

Writes one configuration entry. Insert failures roll back an enclosing audited mutation; a standalone call returns the error. Entries are announced only after the transaction owned by this module commits.

opts are the context call's: :actor_uuid, and :mode (default "manual" with an actor, "auto" without). audit: false writes nothing (:skipped) — for a change one context makes to another's rows as a consequence of the one that is recorded. metadata is a map of string keys.

@spec log_damage(PhoenixKit.Modules.Storage.File.t(), [map()], keyword()) :: :ok

Writes one storage.copy.damaged entry for each result of a verification (FileReport.verify/1) that is a copy missing from its bucket or differing from its checksum, against that bucket. A copy that could not be read is not damage (the bucket may only be unreachable), and a user's own bucket is private. opts are the audit options (:actor_uuid) and :found_by ("verify" or "repair"). Never raises.

@spec log_repair(
  PhoenixKit.Modules.Storage.File.t(),
  [map()],
  non_neg_integer(),
  keyword()
) :: :ok

Writes the storage.file.repaired entry of a repair of file: the actions it took (rendition, what, which bucket) and how many problems were left. Nothing is written when nothing was done. Never raises.

@spec log_update(String.t(), String.t(), String.t() | nil, keyword(), map(), map()) ::
  :ok

Logs an update, when changes is not empty; extra is merged into the metadata.

@spec module_key() :: String.t()

The Activity module key every storage entry (configuration and runs) is filed under.

@spec transaction((-> result)) :: result | {:error, term()} when result: var

Runs a configuration mutation and its audit inserts in one transaction, then announces the entries after commit. Nested audited mutations share the entries. A failed mutation or audit insert rolls everything back.

Inside a caller's own repo transaction, entries commit with that transaction but are not announced: this module cannot know when the caller commits. The History tab's periodic refresh picks them up. Call this wrapper at the outer boundary when immediate announcements are wanted.