@spec capture_fingerprint(String.t(), Ecto.UUID.t(), map()) :: :ok

Records the PER-FIELD fingerprints of source_fields for {resource_type, uuid} in the CALLING PROCESS's dictionary. Meant to be called from inside a source_fields/2 implementation, right before the value is handed to the AI engine — see the moduledoc.

@spec captured_fingerprint(String.t(), Ecto.UUID.t()) ::
  %{required(String.t()) => String.t()} | nil

Reads back the per-field fingerprints captured earlier in THIS process, or nil.

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

sha256 hex digest of a single trimmed field value.

@spec field_fingerprints(map()) :: %{required(String.t()) => String.t()}

Applies field_fingerprint/1 to every entry of a source_fields/2-shaped map.

@spec field_state(struct(), String.t(), String.t()) :: state() | nil

The freshness state of a single FIELD of resource's translation into lang. nil when field currently has no non-empty source text — such a field is excluded from state/2's fold and its translation, if any, is left untouched by the write path.

@spec fingerprint(map()) :: String.t()

sha256 hex digest of source_fields, order-independent: fields are sorted by key, each rendered as "field=trimmed value", joined by "\n".

Kept for callers that want a single whole-resource digest (and for the legacy-format discussion in the moduledoc); the per-field model below (field_fingerprint/1 / field_fingerprints/1) is what gets written to storage now.

@spec list(:item | :category | :set_label | :set_value, keyword()) :: [map()]

Lists (resource, language) rows for type, one per language in opts[:langs].

Options

• :langs — target languages to report on (default [] — an empty list yields no rows; callers pick the languages that matter to them, e.g. the enabled non-default set or a single language filter)
• :state — one state atom or a list of them; unfiltered when absent
• :catalogue_uuid — scope :item/:category rows to one catalogue (ignored for :set_label/:set_value, which are catalogue-wide)
• :page / :per_page — 1-indexed pagination (defaults 1 / 50)

@spec reset_baseline(struct(), String.t(), String.t() | [String.t()]) ::
  {:ok, struct()} | {:error, term()}

"Reset baseline" (design source §4.4): deletes the stored fingerprints of fields (a field name or a list of them) for lang, WITHOUT touching the translation itself or calling the AI. A field with no stored fingerprint is left alone (no-op for that field). The pair drops to :unknown for each reset field until the next successful write — the sweep never auto-picks up :unknown, so a forced re-translate stays a deliberate, visible operator action rather than a sweep-driven loop.

@spec stamp_all_translated(struct()) :: struct()

Stamps every language that currently holds a translation of resource as :fresh against the CURRENT source — the create-time baseline. A resource saved from the form with translations already in hand (a value-mode AI translate on a not-yet-saved item, a secondary-language name typed by hand) was translated against the source it is created with, so it must not be born :unknown — a state the sweep never picks up and an operator would otherwise clear by hand, language by language (week review, 2026-09-13). Item and category only; anything else returns unchanged. Never raises: a stamp that fails leaves that pair :unknown, which is what it was.

@spec stamp_fresh(struct(), String.t()) :: {:ok, struct()} | {:error, term()}

Operator action: "the current source is canonical" — writes the CURRENT source's fingerprint under lang for every field that is both currently sourced and translated, without calling the AI. Flips the resource to :fresh for lang (or leaves it alone — see the guard below: a resource with no translation for lang has nothing to stamp).

@spec stamp_fresh(struct(), String.t(), String.t() | [String.t()]) ::
  {:ok, struct()} | {:error, term()}

Field-narrowed stamp_fresh/2: stamps only fields (a field name or a list of them), leaving every other field's stored fingerprint as-is. A field is skipped (no-op) unless it is both currently sourced AND translated; the call as a whole fails with {:error, :no_translation} only when NONE of the requested fields qualify.

@spec stamp_preimage(struct(), String.t(), %{required(String.t()) => String.t()}) ::
  {:ok, struct()} | {:error, term()}

Sync/operator action: "the value I'm about to overwrite is the reference" — writes fingerprints computed from previous_source_fields (a map of ENGINE field name => the value being REPLACED, not the resource's current value) under lang, for exactly the fields named there. Every other field's stored fingerprint is left untouched, same as stamp_fresh/3's narrowing.

For a caller (a Shopify sync, say) that is about to overwrite the PRIMARY-language source of one or more fields and already knows the value it's replacing: stamping that value FIRST turns the (resource, lang) pair :stale once the sync's own write lands — "this translation was made against real prior text" — instead of :unknown, which the sweep worker never auto-picks up (see the moduledoc).

Refuses exactly like stamp_fresh/2: {:error, :no_translation} when lang has no translation at all. Locked FOR UPDATE, same as stamp_fresh/2 and /3.

@spec state(struct(), String.t()) :: state()

The freshness state of resource's translation into lang, folded (worst wins) across every field that currently has non-empty source text. :missing when no field currently has source text at all but something is translated for lang would be surprising — that resource simply reports :missing (nothing eligible to translate) unless it is itself translated, in which case :unknown (see moduledoc).

@spec stored_fingerprint_map(struct(), String.t()) :: %{
  required(String.t()) => String.t()
}

The WHOLE per-field fingerprint map stored for resource/lang (%{field => hash}), or %{} if there is none. A legacy single-hash string at that key (see moduledoc) is treated as %{} — absent, not a match for any field.