@spec cast_id(module(), t() | String.t()) ::
  {:ok, term()} | {:error, AuditLog.InvalidValueError.t()}

Casts a stored text identifier through a schema's single primary-key type.

Accepts either an AuditLog.Subject or a stored subject ID. Use the result to query an application schema whose primary key is an integer, UUID, or custom Ecto type.

@spec cast_id!(module(), t() | String.t()) :: term()

Casts a stored subject ID or raises AuditLog.InvalidValueError.

Use cast_id/2 when a stored ID may not match the application schema.

@spec from_schema(
  Ecto.Schema.t(),
  keyword()
) :: {:ok, t()} | {:error, AuditLog.InvalidValueError.t()}

Validates one loaded or deleted Ecto schema struct and builds its subject.

The schema must have one non-nil primary key. from_schema/2 uses the schema source as the subject type unless the caller supplies :type.

If the caller omits :version_at, from_schema/2 reads either a structurally compatible sys_period.from or a Postgrex.Range lower boundary. An explicit :version_at takes precedence.

@spec from_schema!(
  Ecto.Schema.t(),
  keyword()
) :: t()

Builds a subject from a schema struct or raises AuditLog.InvalidValueError.

Use from_schema/2 when the caller can recover from an invalid schema or temporal value.

@spec new(term(), term(), keyword()) ::
  {:ok, t()} | {:error, AuditLog.InvalidValueError.t()}

Validates an application-owned subject type and identifier.

type and id must implement String.Chars. new/3 converts both values to strings, trims them, and rejects blank results.

Use :version_at to identify the lower boundary of an exact temporal row version:

AuditLog.Subject.new("invoice", 42, version_at: version_boundary)

@spec new!(term(), term(), keyword()) :: t()

Validates a subject and returns it, or raises AuditLog.InvalidValueError.

Use this function only when invalid input is exceptional. Use new/3 for runtime identifiers.