Threadline.Audit (Threadline v0.6.0)

Audited write-path helper — one call for transaction-local actor GUC, domain writes, optional semantic action linkage, and audit_transaction_id on success.

Call from Phoenix context modules (or Oban workers) after Threadline.Plug / Threadline.Job have resolved %Threadline.Semantics.AuditContext{} and %Threadline.Semantics.ActorRef{}. The helper does not replace those edge modules.

Options

:actor_ref — %Threadline.Semantics.ActorRef{} (required unless audit_context: or allow_missing_actor: true on capture-only paths)
:audit_context — %Threadline.Semantics.AuditContext{}; supplies actor_ref, correlation_id, and request_id (top-level opts override)
:action — atom or {:name, action_opts} for Threadline.record_action/2 after the callback succeeds; links audit_transactions.action_id via txid_current() (correlation-ready path)
:capture_only — same as omitting :action (capture-only path)
:allow_missing_actor — when true and :action is absent, permits nil actor_ref (non-recommended for multi-tenant SaaS)
:transaction_meta — map stored on audit_transactions.meta on both correlation-ready (:action present) and capture-only paths
:correlation_id, :request_id, :job_id — forwarded to record_action/2 when :action is an atom

Capture-only vs correlation-ready

`:action`	Strict `:correlation_id` timeline/export
present	correlation-ready — `action_id` linked
absent	capture-only — strict filters won't match

See Threadline.Query.timeline/2 for strict :correlation_id semantics.

Callback contract

Pass fn -> domain_result end with Repo captured in the closure.

Allowed: domain inserts/updates/deletes; Repo.rollback/1 on failure.

Forbidden inside the callback: set_config for threadline.actor_ref, Threadline.record_action/2, and nested Repo.transaction/1 (breaks GUC and txid_current() linkage).

Return shape

On success, returns {:ok, result} where result is the callback return with :audit_transaction_id merged when capture produced an audit_transactions row (map callback) or wrapped as %{result: value, audit_transaction_id: id} for non-map returns. On failure, {:error, reason} (:missing_actor, :missing_audit_transaction_for_link, changesets, or rollback reasons).

Errors

{:error, :missing_actor} — nil actor_ref when required
{:error, :missing_audit_transaction_for_link} — linkage update_all count != 1

Summary

Types

action_opt()

Functions

transaction(repo, opts, fun)

Runs fun inside repo.transaction/1 after setting the transaction-local threadline.actor_ref GUC and optionally recording a semantic action.

Types

action_opt()

@type action_opt() :: atom() | {atom(), keyword()}

Functions

transaction(repo, opts, fun)

@spec transaction(module(), keyword(), (-> term())) ::
  {:ok, term()} | {:error, term()}

Runs fun inside repo.transaction/1 after setting the transaction-local threadline.actor_ref GUC and optionally recording a semantic action.

See module doc for options, callback rules, and return envelope.